orynn 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,152 @@
 import * as react from 'react';
-import { ComponentType, SyntheticEvent, SelectHTMLAttributes, ReactNode, ChangeEvent, InputHTMLAttributes, FormEvent } from 'react';
+import { ReactNode, HTMLAttributes, InputHTMLAttributes, ChangeEvent, ComponentType, SyntheticEvent, TextareaHTMLAttributes, CSSProperties, FormEvent } from 'react';
+
+type ControlSize = "sm" | "md" | "lg";
+type ControlVariant = "outline" | "filled" | "flushed" | "unstyled";
+type ControlRadius = "none" | "sm" | "md" | "lg" | "pill";
+interface FieldBoxOwnProps {
+    size?: ControlSize;
+    variant?: ControlVariant;
+    radius?: ControlRadius;
+    disabled?: boolean;
+    invalid?: boolean;
+    /** Success / valid visual state. */
+    valid?: boolean;
+    /** Controlled focus ring. Omit to auto-track via focus-within. */
+    focused?: boolean;
+    /** Whether the floating label is raised (usually focused || has value). */
+    active?: boolean;
+    /** Rotates a chevron marked `.orynn-select__chevron`. */
+    open?: boolean;
+    /** Floating label node (usually a `<label class="orynn-box__label">`). */
+    floatingLabel?: ReactNode;
+    left?: ReactNode;
+    right?: ReactNode;
+    /** Adds `.orynn-box--textarea` sizing. */
+    textarea?: boolean;
+}
+interface FieldBoxProps extends FieldBoxOwnProps, Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    children: ReactNode;
+}
+declare const FieldBox: react.ForwardRefExoticComponent<FieldBoxProps & react.RefAttributes<HTMLDivElement>>;
+
+/** One message, several messages, or nothing. */
+type Feedback = string | string[] | undefined;
+/**
+ * Props shared by every labelled control (Input, Textarea, NumberField,
+ * Dropdown, DatePicker, …). Individual controls add their own on top.
+ */
+interface BaseControlProps {
+    label?: ReactNode;
+    /** Help text under the label. */
+    description?: ReactNode;
+    /** Error message(s). Presence puts the control in its invalid state. */
+    error?: Feedback;
+    /** Success state — `true`, or a confirmation message to show. */
+    success?: string | boolean;
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    size?: ControlSize;
+    variant?: ControlVariant;
+    radius?: ControlRadius;
+    /** Render the label floating inside the control border. */
+    floatingLabel?: boolean;
+    /** Content before the field (icon, text). */
+    startContent?: ReactNode;
+    /** Content after the field (icon, text). */
+    endContent?: ReactNode;
+    /** Show an ✕ button to clear the value. */
+    clearable?: boolean;
+    onClear?: () => void;
+    /** Show a spinner in the end slot. */
+    loading?: boolean;
+    id?: string;
+    name?: string;
+    className?: string;
+}
+
+type NativeCheckbox = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange" | "size" | "value">;
+interface CheckboxProps extends NativeCheckbox {
+    label?: ReactNode;
+    description?: ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    indeterminate?: boolean;
+    onChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Value used when inside a `<CheckboxGroup>`. */
+    value?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    size?: ControlSize;
+    /** `"filled"` (default) paints the box on check; `"outline"` keeps it hollow. */
+    variant?: "filled" | "outline";
+    /** Put the label before the box. */
+    labelPlacement?: "end" | "start";
+    /** Bordered selectable card. */
+    card?: boolean;
+    /** Custom checked / indeterminate glyphs. */
+    icon?: ReactNode;
+    indeterminateIcon?: ReactNode;
+    className?: string;
+}
+declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
+
+interface CheckboxOption {
+    label: ReactNode;
+    value: string;
+    description?: ReactNode;
+    disabled?: boolean;
+}
+interface CheckboxGroupProps {
+    label?: ReactNode;
+    description?: ReactNode;
+    error?: Feedback;
+    success?: string | boolean;
+    required?: boolean;
+    disabled?: boolean;
+    name?: string;
+    size?: ControlSize;
+    value?: string[];
+    defaultValue?: string[];
+    onChange?: (value: string[]) => void;
+    orientation?: "vertical" | "horizontal";
+    /** Minimum selections (blocks unchecking below it). */
+    min?: number;
+    /** Maximum selections (blocks checking above it). */
+    max?: number;
+    /** Convenience: render items from data instead of children. */
+    options?: CheckboxOption[];
+    children?: ReactNode;
+    className?: string;
+    id?: string;
+}
+declare function CheckboxGroup(props: CheckboxGroupProps): react.JSX.Element;
+
+interface DatePickerProps extends Omit<BaseControlProps, "startContent" | "endContent" | "loading"> {
+    value?: Date | string | null;
+    defaultValue?: Date | string | null;
+    onChange?: (value: Date | null) => void;
+    /** Display / parse pattern (`yyyy MM dd M d MMM MMMM`). Default `"yyyy-MM-dd"`. */
+    format?: string;
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDates?: Date[] | ((date: Date) => boolean);
+    firstDayOfWeek?: number;
+    locale?: string;
+    showWeekNumbers?: boolean;
+    showToday?: boolean;
+    showClear?: boolean;
+    /** Render the calendar always, without a text field. */
+    inline?: boolean;
+    /** Allow typing a date into the field. Default true. */
+    allowInput?: boolean;
+    closeOnSelect?: boolean;
+    placeholder?: string;
+}
+declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
 
 /**
  * Per-field validation config. V1 ships `required` / `minLength` / `maxLength`.
@@ -48,11 +195,17 @@ type ValidationResolver = (values: Record<string, unknown>, config: FieldsetConf
  */
 type RuleFn = (value: unknown, param: unknown, allValues: Record<string, unknown>) => string | null;
 
-/** A single selectable option in a {@link DropdownFieldConfig}. */
+/** A single selectable option for `Dropdown` / a {@link DropdownFieldConfig}. */
 interface DropdownOption {
     label: string;
     value: string;
     disabled?: boolean;
+    /** Secondary line under the label. */
+    description?: ReactNode;
+    /** Leading icon / flag. */
+    icon?: ReactNode;
+    /** Group heading this option is listed under. */
+    group?: string;
 }
 /** Number of columns at each responsive breakpoint. */
 interface ColumnSpec {
@@ -118,6 +271,39 @@ interface FieldsetConfig {
     id?: string;
 }
 
+interface OptionState {
+    selected: boolean;
+    active: boolean;
+    disabled: boolean;
+    /** Query the option matched, for highlighting. */
+    query: string;
+}
+interface DropdownProps extends Omit<BaseControlProps, "startContent" | "endContent"> {
+    options: DropdownOption[];
+    value?: string | string[] | null;
+    defaultValue?: string | string[] | null;
+    onChange?: (value: string | string[] | null) => void;
+    multiple?: boolean;
+    /** Type in the control to filter options. */
+    searchable?: boolean;
+    filterMode?: "contains" | "startsWith";
+    filterFn?: (option: DropdownOption, query: string) => boolean;
+    /** Bold the matched substring in option labels. Default true when searchable. */
+    highlightMatch?: boolean;
+    renderOption?: (option: DropdownOption, state: OptionState) => ReactNode;
+    renderValue?: (selected: DropdownOption[]) => ReactNode;
+    placeholder?: string;
+    emptyMessage?: ReactNode;
+    /** Close the panel after a pick. Default true for single, false for multiple. */
+    closeOnSelect?: boolean;
+    /** Cap the chips shown before "+N". */
+    maxSelectedLabels?: number;
+    /** Fall back to a native `<select>` (single, no search). */
+    native?: boolean;
+    startContent?: ReactNode;
+}
+declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLInputElement>>;
+
 /**
  * The contract every control receives from `Fieldset`. This is the stability
  * boundary between the orchestrator and the controls: as long as this holds,
@@ -178,43 +364,30 @@ interface FieldRenderContext {
     /** Value for the control's `aria-describedby`, or `undefined`. */
     describedById: string | undefined;
     invalid: boolean;
+    valid: boolean;
     required: boolean | undefined;
     disabled: boolean | undefined;
 }
 /**
- * Low-level layout + a11y wrapper. Renders label, description and error region
- * and wires the ARIA relationships. `Input` and `Dropdown` are built on it, and
- * it is exported for custom control authors.
+ * Low-level layout + a11y wrapper. Renders label, description and an
+ * error / success region and wires the ARIA relationships. Every control is
+ * built on it, and it is exported for custom control authors.
  */
 interface FieldProps {
     label?: ReactNode;
     description?: ReactNode;
     error?: ErrorProp;
+    /** `true`, or a confirmation message, to show the success state. */
+    success?: string | boolean;
     required?: boolean;
     disabled?: boolean;
+    /** Skip rendering the `<label>` (e.g. the control floats its own). */
+    hideLabel?: boolean;
     /** Control id; generated with `useId` when omitted. */
     id?: string;
     className?: string;
     children: ReactNode | ((ctx: FieldRenderContext) => ReactNode);
 }
-/** Props shared by the standalone controls. */
-interface SharedControlProps {
-    label?: ReactNode;
-    description?: ReactNode;
-    error?: ErrorProp;
-}
-interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value" | "type">, SharedControlProps {
-    value?: string;
-    onChange?: (value: string, event?: ChangeEvent<HTMLInputElement>) => void;
-    type?: "text" | "email" | "password" | "number" | "tel" | "url";
-}
-interface DropdownProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "onChange" | "value">, SharedControlProps {
-    options: DropdownOption[];
-    value?: string;
-    onChange?: (value: string, event?: ChangeEvent<HTMLSelectElement>) => void;
-    /** Renders a non-selectable prompt option when the value is empty. */
-    placeholder?: string;
-}
 interface FieldsetProps<TValues extends Record<string, unknown> = Record<string, unknown>> {
     config: FieldsetConfig;
     /** Controlled values. Omit and use `defaultValue` for uncontrolled. */
@@ -234,18 +407,10 @@ interface FieldsetProps<TValues extends Record<string, unknown> = Record<string,
     id?: string;
 }
 
-/**
- * A labelled single-select built on the native `<select>` element (accessible
- * and keyboard-navigable out of the box). Works with or without `<Fieldset>`.
- */
-declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLSelectElement>>;
-
 /**
  * Layout + accessibility wrapper for a single control. Renders the label,
- * optional description, and an error region, and wires the ARIA relationships
- * (`htmlFor`, `aria-describedby`, `aria-invalid`, `aria-required`).
- *
- * Pass a render function as `children` to receive the resolved ids:
+ * optional description, and an error/success region, and wires the ARIA
+ * relationships (`htmlFor`, `aria-describedby`, `aria-invalid`, `aria-required`).
  *
  * ```tsx
  * <Field label="Name" error={error}>
@@ -257,13 +422,110 @@ declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.Re
  */
 declare function Field(props: FieldProps): react.JSX.Element;
 
-/**
- * A labelled text input. Controlled when `value` is passed, uncontrolled
- * otherwise (`defaultValue` flows through to the native element). Works with or
- * without `<Fieldset>`.
- */
+type NativeInput = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "type" | "size" | "prefix">;
+interface InputProps extends BaseControlProps, NativeInput {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Fired on Enter. */
+    onEnter?: (value: string) => void;
+    type?: "text" | "email" | "password" | "search" | "tel" | "url";
+    /** Static text glued to the start (e.g. `https://`). */
+    prefix?: ReactNode;
+    /** Static text glued to the end (e.g. `.com`). */
+    suffix?: ReactNode;
+    /** Show a show/hide toggle (implied for `type="password"`). */
+    passwordToggle?: boolean;
+    /** Show a live character counter. Pairs well with `maxLength`. */
+    showCount?: boolean;
+}
 declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
 
+type NativeNumberInput = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "type" | "min" | "max" | "step" | "size" | "prefix">;
+interface NumberFieldProps extends BaseControlProps, NativeNumberInput {
+    value?: number | null;
+    defaultValue?: number | null;
+    onChange?: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Larger step for Shift+Arrow / PageUp-Down. Default `step * 10`. */
+    shiftStep?: number;
+    /** Decimal places to keep. */
+    precision?: number;
+    /** Stepper buttons. Default `"stacked"`. */
+    buttons?: "stacked" | "horizontal" | false;
+    /** Group thousands (`1,000`). */
+    grouping?: boolean;
+    /** BCP-47 locale for formatting. */
+    locale?: string;
+    /** ISO currency code — renders as currency. */
+    currency?: string;
+    /** Text before the number. */
+    prefix?: string;
+    /** Text after the number (e.g. `%`, `kg`). */
+    suffix?: string;
+    /** Clamp to `[min, max]` on blur. Default true. */
+    clampOnBlur?: boolean;
+    /** Step with the mouse wheel while focused. Default false. */
+    allowMouseWheel?: boolean;
+}
+declare const NumberField: react.ForwardRefExoticComponent<NumberFieldProps & react.RefAttributes<HTMLInputElement>>;
+
+type NativeRadio = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange" | "size" | "value">;
+interface RadioProps extends NativeRadio {
+    value: string;
+    label?: ReactNode;
+    description?: ReactNode;
+    disabled?: boolean;
+    size?: ControlSize;
+    card?: boolean;
+    labelPlacement?: "end" | "start";
+    className?: string;
+}
+declare const Radio: react.ForwardRefExoticComponent<RadioProps & react.RefAttributes<HTMLInputElement>>;
+interface RadioOption {
+    label: ReactNode;
+    value: string;
+    description?: ReactNode;
+    disabled?: boolean;
+}
+interface RadioGroupProps {
+    label?: ReactNode;
+    description?: ReactNode;
+    error?: Feedback;
+    success?: string | boolean;
+    required?: boolean;
+    disabled?: boolean;
+    name?: string;
+    size?: ControlSize;
+    variant?: "default" | "card";
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string) => void;
+    orientation?: "vertical" | "horizontal";
+    options?: RadioOption[];
+    children?: ReactNode;
+    className?: string;
+    id?: string;
+}
+declare function RadioGroup(props: RadioGroupProps): react.JSX.Element;
+
+type NativeTextarea = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue" | "onChange" | "rows" | "cols">;
+interface TextareaProps extends Omit<BaseControlProps, "startContent" | "endContent" | "loading">, NativeTextarea {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string, event: ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Grow with content between `minRows` and `maxRows`. */
+    autoResize?: boolean;
+    minRows?: number;
+    maxRows?: number;
+    /** Native resize handle. Default `"vertical"` (`"none"` when `autoResize`). */
+    resize?: "none" | "vertical" | "both";
+    showCount?: boolean;
+}
+declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
+
 /**
  * Renders a form (or a form section) from a `FieldsetConfig`. Controlled when
  * `value` is passed, uncontrolled otherwise. Renders a native `<fieldset>` — so
@@ -272,6 +534,62 @@ declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttri
  */
 declare function Fieldset<TValues extends Record<string, unknown> = Record<string, unknown>>(props: FieldsetProps<TValues>): react.JSX.Element;
 
+/** Built-in colour presets. Each maps to `[data-orynn-theme="…"]` in the stylesheet. */
+type OrynnPreset = "default" | "slate" | "teal" | "violet" | "rose" | "emerald";
+/** Vertical rhythm / sizing. Maps to `[data-orynn-density="…"]`. */
+type OrynnDensity = "compact" | "comfortable" | "spacious";
+type OrynnRadius = "none" | "sm" | "md" | "lg" | "pill" | (string & {}) | number;
+/** Any `--orynn-*` custom property. */
+type OrynnVarOverrides = Partial<Record<`--orynn-${string}`, string | number>>;
+interface OrynnThemeConfig {
+    /** Colour preset. Defaults to `"default"` (indigo). */
+    preset?: OrynnPreset;
+    density?: OrynnDensity;
+    /** Highlight / accent colour. Any CSS colour — overrides the preset's accent. */
+    accent?: string;
+    /** Foreground colour to pair with a custom `accent` (auto-picked from luminance if omitted). */
+    accentContrast?: string;
+    /** `--orynn-font-family`. */
+    font?: string;
+    /** Base font size, e.g. `"15px"` or `"0.95rem"`. */
+    fontSize?: string | number;
+    /** Corner radius applied to controls. Keyword, CSS length, or px number. */
+    radius?: OrynnRadius;
+    /** Default control width. `"100%"` by default; e.g. `"20rem"` or `320`. */
+    controlWidth?: string | number;
+    /** Focus-ring colour. */
+    ring?: string;
+    /** Escape hatch: any `--orynn-*` variables verbatim. */
+    vars?: OrynnVarOverrides;
+}
+/** `theme` prop accepts a preset name shorthand or a full config. */
+type OrynnThemeInput = OrynnPreset | OrynnThemeConfig;
+/** Build the inline CSS-variable style object for a theme config. */
+declare function resolveThemeVars(config: OrynnThemeConfig): CSSProperties;
+
+interface OrynnContextValue {
+    preset: OrynnPreset;
+    density: OrynnDensity;
+    config: OrynnThemeConfig;
+}
+interface OrynnProviderProps {
+    /** Preset name (`"teal"`) or a full config object. */
+    theme?: OrynnThemeInput;
+    /** Render a `<div>` (default) or a different element / no wrapper (`"contents"`). */
+    as?: "div" | "span" | "contents";
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Scopes an Orynn theme to its subtree by setting `data-orynn-theme`,
+ * `data-orynn-density` and any custom `--orynn-*` variables on a wrapper element.
+ * Purely CSS custom properties — no runtime styling engine. Nesting is supported;
+ * an inner provider overrides only what it sets.
+ */
+declare function OrynnProvider({ theme, as, className, children }: OrynnProviderProps): react.JSX.Element;
+/** Read the nearest Orynn theme config. */
+declare function useOrynnTheme(): OrynnContextValue;
+
 /** Form-level validation roll-up. */
 type FieldStatus = "idle" | "validating" | "valid" | "invalid";
 /** The complete state a fieldset tracks. New keys must be additive. */
@@ -397,4 +715,4 @@ declare const defaultResolver: ValidationResolver;
  */
 declare function registerRule(name: string, fn: RuleFn): void;
 
-export { type BaseFieldConfig, type ColumnSpec, type ControlComponent, type ControlProps, Dropdown, type DropdownFieldConfig, type DropdownOption, type DropdownProps, type ErrorProp, FORM_ERROR_KEY, Field, type FieldConfig, type FieldConfigRegistry, type FieldError, type FieldProps, type FieldRegistration, type FieldRegistry, type FieldRenderContext, type FieldSlice, type FieldStatus, type FieldType, type FieldValidation, Fieldset, type FieldsetConfig, type FieldsetProps, type FieldsetState, Input, type InputFieldConfig, type InputProps, type NormalizedFieldsetConfig, type RuleFn, type SyncResolver, type UseFieldsetStateOptions, type UseFieldsetStateReturn, type ValidationContext, type ValidationResolver, type ValidationResult, type ValidationTrigger, createRegistry, createRuleResolver, defaultRegistry, defaultResolver, normalizeConfig, registerField, registerRule, useFieldsetState };
+export { type BaseControlProps, type BaseFieldConfig, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxOption, type CheckboxProps, type ColumnSpec, type ControlComponent, type ControlProps, type ControlRadius, type ControlSize, type ControlVariant, DatePicker, type DatePickerProps, Dropdown, type DropdownFieldConfig, type DropdownOption, type DropdownProps, type ErrorProp, FORM_ERROR_KEY, type Feedback, Field, FieldBox, type FieldBoxProps, type FieldConfig, type FieldConfigRegistry, type FieldError, type FieldProps, type FieldRegistration, type FieldRegistry, type FieldRenderContext, type FieldSlice, type FieldStatus, type FieldType, type FieldValidation, Fieldset, type FieldsetConfig, type FieldsetProps, type FieldsetState, Input, type InputFieldConfig, type InputProps, type NormalizedFieldsetConfig, NumberField, type NumberFieldProps, type OrynnDensity, type OrynnPreset, OrynnProvider, type OrynnProviderProps, type OrynnRadius, type OrynnThemeConfig, type OrynnThemeInput, type OrynnVarOverrides, Radio, RadioGroup, type RadioGroupProps, type RadioOption, type RadioProps, type RuleFn, Dropdown as Select, type SyncResolver, Textarea, type TextareaProps, type UseFieldsetStateOptions, type UseFieldsetStateReturn, type ValidationContext, type ValidationResolver, type ValidationResult, type ValidationTrigger, createRegistry, createRuleResolver, defaultRegistry, defaultResolver, normalizeConfig, registerField, registerRule, resolveThemeVars, useFieldsetState, useOrynnTheme };