lucent-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,687 @@
+import { ButtonHTMLAttributes } from 'react';
+import { CSSProperties } from 'react';
+import { default as default_2 } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { ImgHTMLAttributes } from 'react';
+import { InputHTMLAttributes } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+import { SelectHTMLAttributes } from 'react';
+import { TextareaHTMLAttributes } from 'react';
+
+export declare interface AccessibilityDescriptor {
+    /** ARIA role applied to the root element */
+    role?: string;
+    /** ARIA attributes used by this component */
+    ariaAttributes?: string[];
+    /** Keyboard interactions supported */
+    keyboardInteractions?: string[];
+    /** Plain-English notes for screen reader behaviour */
+    notes?: string;
+}
+
+export declare function Alert({ variant, title, children, onDismiss, icon, style, }: AlertProps): JSX_2.Element;
+
+export declare const AlertManifest: ComponentManifest;
+
+export declare interface AlertProps {
+    variant?: AlertVariant;
+    title?: string;
+    children?: ReactNode;
+    onDismiss?: () => void;
+    icon?: ReactNode;
+    style?: CSSProperties;
+}
+
+export declare type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
+
+/**
+ * Asserts a manifest is valid. Throws a descriptive error if not.
+ * Use in tests or at component module load time.
+ */
+export declare function assertManifest(manifest: unknown): asserts manifest is ComponentManifest;
+
+export declare function Avatar({ src, alt, size, initials, style, ...rest }: AvatarProps): JSX_2.Element;
+
+export declare const AvatarManifest: ComponentManifest;
+
+export declare interface AvatarProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'alt'> {
+    src?: string;
+    alt: string;
+    size?: AvatarSize;
+    initials?: string;
+}
+
+export declare type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export declare function Badge({ variant, size, dot, children }: BadgeProps): JSX_2.Element;
+
+export declare const BadgeManifest: ComponentManifest;
+
+export declare interface BadgeProps {
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    children: ReactNode;
+    dot?: boolean;
+}
+
+export declare type BadgeSize = 'sm' | 'md';
+
+export declare type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'accent';
+
+/**
+ * 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.
+ *
+ * @example
+ * import { brandTokens } from 'lucent-ui';
+ * <LucentProvider tokens={brandTokens}><App /></LucentProvider>
+ */
+export declare const brandTokens: Partial<LucentTokens>;
+
+export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>;
+
+export declare const ButtonManifest: ComponentManifest;
+
+export declare interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    loading?: boolean;
+    fullWidth?: boolean;
+    leftIcon?: ReactNode;
+    rightIcon?: ReactNode;
+    /** Appends a chevron-down icon after the label (or rightIcon). Useful for dropdown triggers. */
+    chevron?: boolean;
+}
+
+export declare type ButtonSize = 'sm' | 'md' | 'lg';
+
+export declare type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+
+export declare function Card({ header, footer, children, padding, shadow, radius, style, }: CardProps): JSX_2.Element;
+
+export declare const CardManifest: ComponentManifest;
+
+export declare type CardPadding = 'none' | 'sm' | 'md' | 'lg';
+
+export declare interface CardProps {
+    header?: ReactNode;
+    footer?: ReactNode;
+    children: ReactNode;
+    padding?: CardPadding;
+    shadow?: CardShadow;
+    radius?: CardRadius;
+    style?: CSSProperties;
+}
+
+export declare type CardRadius = 'none' | 'sm' | 'md' | 'lg';
+
+export declare type CardShadow = 'none' | 'sm' | 'md' | 'lg';
+
+export declare const Checkbox: ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLInputElement>>;
+
+export declare const CheckboxManifest: ComponentManifest;
+
+export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+    label?: string;
+    size?: CheckboxSize;
+    indeterminate?: boolean;
+}
+
+export declare type CheckboxSize = 'sm' | 'md';
+
+/**
+ * The domain of a component.
+ * "neutral" means the component is domain-agnostic and reusable
+ * across any product context.
+ */
+export declare type ComponentDomain = 'neutral' | string;
+
+export declare interface ComponentManifest {
+    /**
+     * Unique identifier — kebab-case, e.g. "button", "form-field"
+     */
+    id: string;
+    /** Display name shown in docs and tooling */
+    name: string;
+    /** Position in the design system hierarchy */
+    tier: ComponentTier;
+    /**
+     * Product domain this component belongs to.
+     * Use "neutral" for general-purpose components.
+     */
+    domain: ComponentDomain;
+    /** One-sentence description for AI context */
+    description: string;
+    /** All accepted props */
+    props: readonly PropDescriptor[];
+    /** Code examples an AI can use to generate correct usage */
+    usageExamples: readonly UsageExample[];
+    /**
+     * For molecules, blocks, flows and overlays — the sub-components
+     * this component is composed from.
+     */
+    compositionGraph: readonly CompositionNode[];
+    /**
+     * Design intent: explain the "why" behind visual and interaction decisions.
+     * This is the key field for AI-legibility — it conveys context that
+     * prop types alone cannot.
+     */
+    designIntent: string;
+    /** Accessibility metadata */
+    accessibility?: AccessibilityDescriptor;
+    /**
+     * Spec version this manifest conforms to.
+     * Format: "MAJOR.MINOR" — e.g. "0.1"
+     */
+    specVersion: string;
+}
+
+/**
+ * The tier of a component in the design system hierarchy.
+ *
+ * - atom:     Indivisible UI primitive (Button, Input, Badge…)
+ * - molecule: Composition of atoms (FormField, Card, Alert…)
+ * - block:    Page-section-level composition (PageHeader, SidebarNav…)
+ * - flow:     Multi-step or stateful sequences (Wizard, Onboarding…)
+ * - overlay:  Layers above page content (Modal, Drawer, Tooltip…)
+ */
+export declare type ComponentTier = 'atom' | 'molecule' | 'block' | 'flow' | 'overlay';
+
+export declare interface CompositionNode {
+    /** Component id this node refers to */
+    componentId: string;
+    /** Human-readable name */
+    componentName: string;
+    /** How it is used in the composition */
+    role: string;
+    /** Whether this sub-component is always present or conditional */
+    required: boolean;
+}
+
+export declare const darkTokens: LucentTokens;
+
+export declare function Divider({ orientation, label, spacing }: DividerProps): JSX_2.Element;
+
+export declare const DividerManifest: ComponentManifest;
+
+export declare type DividerOrientation = 'horizontal' | 'vertical';
+
+export declare interface DividerProps {
+    orientation?: DividerOrientation;
+    label?: string;
+    spacing?: string;
+}
+
+export declare function EmptyState({ illustration, title, description, action, style, }: EmptyStateProps): JSX_2.Element;
+
+export declare const EmptyStateManifest: ComponentManifest;
+
+export declare interface EmptyStateProps {
+    illustration?: ReactNode;
+    title: string;
+    description?: string;
+    action?: ReactNode;
+    style?: CSSProperties;
+}
+
+export declare function FormField({ label, htmlFor, required, helperText, errorMessage, children, style, }: FormFieldProps): JSX_2.Element;
+
+export declare const FormFieldManifest: ComponentManifest;
+
+export declare interface FormFieldProps {
+    label?: string;
+    htmlFor?: string;
+    required?: boolean;
+    helperText?: string;
+    errorMessage?: string;
+    children: ReactNode;
+    style?: CSSProperties;
+}
+
+/**
+ * Returns `'#000000'` or `'#ffffff'` — whichever has higher WCAG contrast
+ * against the given background hex color.
+ *
+ * Use this to guarantee AA-compliant text on any solid accent surface.
+ *
+ * @example
+ * getContrastText('#e9c96b') // → '#000000'  (gold bg → black text, 8.6:1)
+ * getContrastText('#111827') // → '#ffffff'  (near-black bg → white text, 16.7:1)
+ */
+export declare function getContrastText(hex: string): '#000000' | '#ffffff';
+
+export declare function Icon({ children, size, label, color, style }: IconProps): JSX_2.Element;
+
+export declare const IconManifest: ComponentManifest;
+
+export declare interface IconProps {
+    /** The icon element — any SVG or icon-set component. */
+    children: ReactNode;
+    size?: IconSize;
+    /** Accessible label. When provided the wrapper gets role="img". Omit for decorative icons. */
+    label?: string;
+    /** CSS color value. Defaults to currentColor so the icon inherits parent text colour. */
+    color?: string;
+    style?: CSSProperties;
+}
+
+export declare type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export declare const Input: ForwardRefExoticComponent<InputProps & RefAttributes<HTMLInputElement>>;
+
+export declare const InputManifest: ComponentManifest;
+
+export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    type?: InputType;
+    label?: string;
+    helperText?: string;
+    errorText?: string;
+    leftElement?: ReactNode;
+    rightElement?: ReactNode;
+}
+
+export declare type InputType = 'text' | 'number' | 'password' | 'email' | 'tel' | 'url' | 'search';
+
+export declare function isValidPropDescriptor(prop: unknown): prop is PropDescriptor;
+
+export declare const lightTokens: LucentTokens;
+
+export declare const LUCENT_UI_VERSION = "0.1.0";
+
+declare interface LucentContextValue {
+    theme: Theme;
+    tokens: LucentTokens;
+}
+
+/**
+ * Wraps your app (or a subtree) and injects Lucent design tokens
+ * as CSS custom properties into <head>. Uses useLayoutEffect so
+ * styles are applied synchronously before first paint.
+ *
+ * @example
+ * <LucentProvider theme="dark">
+ *   <App />
+ * </LucentProvider>
+ */
+export declare function LucentProvider({ theme, tokens: tokenOverrides, children, }: LucentProviderProps): JSX_2.Element;
+
+export declare interface LucentProviderProps {
+    theme?: Theme;
+    tokens?: Partial<LucentTokens>;
+    children: ReactNode;
+}
+
+export declare interface LucentTokens extends SemanticColorTokens, TypographyTokens, SpacingTokens, RadiusTokens, ShadowTokens, MotionTokens {
+}
+
+/**
+ * Generates a CSS string of custom properties from a token set.
+ * Inject the result into a <style> tag or a CSS-in-JS solution.
+ *
+ * @example
+ * const css = makeLibraryCSS(lightTokens);
+ * document.getElementById('lucent-tokens').textContent = css;
+ */
+export declare function makeLibraryCSS(tokens: LucentTokens, selector?: string): string;
+
+export declare const MANIFEST_SPEC_VERSION = "0.1";
+
+declare interface MotionTokens {
+    durationFast: string;
+    durationBase: string;
+    durationSlow: string;
+    easingDefault: string;
+    easingEmphasized: string;
+    easingDecelerate: string;
+}
+
+export declare interface PropDescriptor {
+    /** Prop name as it appears in the component API */
+    name: string;
+    /** TypeScript type or custom type name */
+    type: PropType;
+    /** Whether the prop is required */
+    required: boolean;
+    /** Default value as a string representation */
+    default?: string;
+    /** Human-readable description for AI and documentation */
+    description: string;
+    /** For enum types — the allowed values */
+    enumValues?: readonly string[];
+}
+
+export declare type PropType = 'string' | 'number' | 'boolean' | 'ReactNode' | 'function' | 'enum' | 'object' | 'array' | 'ref' | string;
+
+export declare function Radio({ value, label, size, disabled, id, onChange, checked, ...rest }: RadioProps): JSX_2.Element;
+
+export declare function RadioGroup({ name, value, onChange, disabled, orientation, label, children, }: RadioGroupProps): JSX_2.Element;
+
+export declare type RadioGroupOrientation = 'vertical' | 'horizontal';
+
+export declare interface RadioGroupProps {
+    name: string;
+    value: string;
+    onChange: (value: string) => void;
+    disabled?: boolean;
+    orientation?: RadioGroupOrientation;
+    label?: string;
+    children: ReactNode;
+}
+
+export declare function RadioGroupUncontrolled({ defaultValue, onChange, ...rest }: RadioGroupUncontrolledProps): JSX_2.Element;
+
+export declare interface RadioGroupUncontrolledProps extends Omit<RadioGroupProps, 'value' | 'onChange'> {
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+}
+
+export declare const RadioManifest: ComponentManifest;
+
+export declare interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+    value: string;
+    label?: string;
+    size?: RadioSize;
+}
+
+export declare type RadioSize = 'sm' | 'md';
+
+declare interface RadiusTokens {
+    radiusNone: string;
+    radiusSm: string;
+    radiusMd: string;
+    radiusLg: string;
+    radiusXl: string;
+    radiusFull: string;
+}
+
+export declare function SearchInput({ value, onChange, placeholder, results, onResultSelect, isLoading, disabled, id, style, }: SearchInputProps): JSX_2.Element;
+
+export declare const SearchInputManifest: ComponentManifest;
+
+export declare interface SearchInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    results?: SearchResult[];
+    onResultSelect?: (result: SearchResult) => void;
+    isLoading?: boolean;
+    disabled?: boolean;
+    id?: string;
+    style?: CSSProperties;
+}
+
+export declare interface SearchResult {
+    id: string | number;
+    label: string;
+}
+
+export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
+
+export declare const SelectManifest: ComponentManifest;
+
+export declare interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+
+export declare interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
+    options: SelectOption[];
+    size?: SelectSize;
+    label?: string;
+    helperText?: string;
+    errorText?: string;
+    placeholder?: string;
+}
+
+export declare type SelectSize = 'sm' | 'md' | 'lg';
+
+declare interface SemanticColorTokens {
+    bgBase: string;
+    bgSubtle: string;
+    bgMuted: string;
+    bgOverlay: string;
+    surfaceDefault: string;
+    surfaceRaised: string;
+    surfaceOverlay: string;
+    borderDefault: string;
+    borderSubtle: string;
+    borderStrong: string;
+    textPrimary: string;
+    textSecondary: string;
+    textDisabled: string;
+    textInverse: string;
+    textOnAccent: string;
+    accentDefault: string;
+    accentHover: string;
+    accentActive: string;
+    accentSubtle: string;
+    successDefault: string;
+    successSubtle: string;
+    successText: string;
+    warningDefault: string;
+    warningSubtle: string;
+    warningText: string;
+    dangerDefault: string;
+    dangerHover: string;
+    dangerSubtle: string;
+    dangerText: string;
+    infoDefault: string;
+    infoSubtle: string;
+    infoText: string;
+    focusRing: string;
+}
+
+declare interface ShadowTokens {
+    shadowNone: string;
+    shadowSm: string;
+    shadowMd: string;
+    shadowLg: string;
+    shadowXl: string;
+}
+
+export declare function Skeleton({ variant, width, height, lines, animate, radius, style, }: SkeletonProps): JSX_2.Element;
+
+export declare const SkeletonManifest: ComponentManifest;
+
+export declare interface SkeletonProps {
+    variant?: SkeletonVariant;
+    width?: string | number;
+    height?: string | number;
+    lines?: number;
+    animate?: boolean;
+    radius?: string;
+    style?: CSSProperties;
+}
+
+export declare type SkeletonVariant = 'text' | 'circle' | 'rectangle';
+
+declare interface SpacingTokens {
+    space0: string;
+    space1: string;
+    space2: string;
+    space3: string;
+    space4: string;
+    space5: string;
+    space6: string;
+    space8: string;
+    space10: string;
+    space12: string;
+    space16: string;
+    space20: string;
+    space24: string;
+}
+
+export declare function Spinner({ size, label, color }: SpinnerProps): JSX_2.Element;
+
+export declare const SpinnerManifest: ComponentManifest;
+
+export declare interface SpinnerProps {
+    size?: SpinnerSize;
+    label?: string;
+    color?: string;
+}
+
+export declare type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg';
+
+export declare function Tag({ children, variant, size, onDismiss, disabled }: TagProps): JSX_2.Element;
+
+export declare const TagManifest: ComponentManifest;
+
+export declare interface TagProps {
+    children: ReactNode;
+    variant?: TagVariant;
+    size?: TagSize;
+    onDismiss?: () => void;
+    disabled?: boolean;
+}
+
+export declare type TagSize = 'sm' | 'md';
+
+export declare type TagVariant = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+
+declare function Text_2({ as, size, weight, color, align, lineHeight, family, truncate, children, style, ...rest }: TextProps): JSX_2.Element;
+export { Text_2 as Text }
+
+export declare type TextAlign = 'left' | 'center' | 'right';
+
+export declare const Textarea: default_2.ForwardRefExoticComponent<TextareaProps & default_2.RefAttributes<HTMLTextAreaElement>>;
+
+export declare const TextareaManifest: ComponentManifest;
+
+export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    label?: string;
+    helperText?: string;
+    errorText?: string;
+    autoResize?: boolean;
+    maxLength?: number;
+    showCount?: boolean;
+}
+
+export declare type TextAs = 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'span' | 'div' | 'label' | 'strong' | 'em' | 'code';
+
+export declare type TextColor = 'primary' | 'secondary' | 'disabled' | 'inverse' | 'onAccent' | 'success' | 'warning' | 'danger' | 'info';
+
+export declare type TextFamily = 'base' | 'mono' | 'display';
+
+export declare type TextLineHeight = 'tight' | 'base' | 'relaxed';
+
+export declare const TextManifest: ComponentManifest;
+
+export declare interface TextProps {
+    as?: TextAs;
+    size?: TextSize;
+    weight?: TextWeight;
+    color?: TextColor;
+    align?: TextAlign;
+    lineHeight?: TextLineHeight;
+    family?: TextFamily;
+    truncate?: boolean;
+    children: ReactNode;
+    style?: CSSProperties;
+    id?: string;
+    htmlFor?: string;
+    className?: string;
+    onClick?: React.MouseEventHandler;
+    title?: string;
+    'aria-label'?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+}
+
+export declare type TextSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+export declare type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+
+export declare type Theme = 'light' | 'dark';
+
+export declare function Toggle({ label, size, checked, defaultChecked, disabled, id, onChange, style, ...rest }: ToggleProps): JSX_2.Element;
+
+export declare const ToggleManifest: ComponentManifest;
+
+export declare interface ToggleProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+    label?: string;
+    size?: ToggleSize;
+    checked?: boolean;
+    defaultChecked?: boolean;
+}
+
+export declare type ToggleSize = 'sm' | 'md' | 'lg';
+
+export declare function Tooltip({ content, children, placement, delay }: TooltipProps): JSX_2.Element;
+
+export declare const TooltipManifest: ComponentManifest;
+
+export declare type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+export declare interface TooltipProps {
+    content: ReactNode;
+    children: ReactNode;
+    placement?: TooltipPlacement;
+    /** Delay in ms before the tooltip appears. Default: 300 */
+    delay?: number;
+}
+
+declare interface TypographyTokens {
+    fontFamilyBase: string;
+    fontFamilyMono: string;
+    fontFamilyDisplay: string;
+    fontSizeXs: string;
+    fontSizeSm: string;
+    fontSizeMd: string;
+    fontSizeLg: string;
+    fontSizeXl: string;
+    fontSize2xl: string;
+    fontSize3xl: string;
+    fontWeightRegular: string;
+    fontWeightMedium: string;
+    fontWeightSemibold: string;
+    fontWeightBold: string;
+    lineHeightTight: string;
+    lineHeightBase: string;
+    lineHeightRelaxed: string;
+    letterSpacingTight: string;
+    letterSpacingBase: string;
+    letterSpacingWide: string;
+}
+
+export declare interface UsageExample {
+    /** Short label for the example */
+    title: string;
+    /** JSX or TSX code string */
+    code: string;
+    /** Optional description of what this example demonstrates */
+    description?: string;
+}
+
+/**
+ * Returns the current Lucent theme and resolved token set.
+ * Must be used inside a <LucentProvider>.
+ */
+export declare function useLucent(): LucentContextValue;
+
+/**
+ * Validates a ComponentManifest object at runtime.
+ * Returns a result object — does not throw.
+ *
+ * @example
+ * const result = validateManifest(ButtonManifest);
+ * if (!result.valid) console.error(result.errors);
+ */
+export declare function validateManifest(manifest: unknown): ValidationResult;
+
+export declare interface ValidationError {
+    field: string;
+    message: string;
+}
+
+export declare interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+
+export { }