@tempots/beatui 1.4.0 → 1.5.0

package/dist/types/components/form/fieldset/fieldset.d.ts

@@ -0,0 +1,60 @@
+import { TNode, Value } from '@tempots/dom';
+import type { ControlSize } from '../../theme';
+import type { FieldLabelLayout } from '../input/field';
+/**
+ * Configuration options for the `Fieldset` component.
+ */
+export interface FieldsetOptions {
+    /** Legend content (always visible header for the fieldset) */
+    legend?: TNode;
+    /** Description text displayed below the legend */
+    description?: TNode;
+    /** Visual variant of the fieldset container. @default 'plain' */
+    variant?: Value<'bordered' | 'plain' | 'card'>;
+    /** Whether the fieldset body can be collapsed/expanded. @default false */
+    collapsible?: Value<boolean>;
+    /** Initial collapsed state (only used when collapsible is true). @default false */
+    defaultCollapsed?: Value<boolean>;
+    /** Whether the entire fieldset (and all children) is disabled. @default false */
+    disabled?: Value<boolean>;
+    /** Label position cascaded to descendant Field components. @default 'vertical' */
+    layout?: Value<FieldLabelLayout>;
+    /** Label column width cascaded to descendant Field components. @default '7.5rem' */
+    labelWidth?: Value<string>;
+    /** Control size cascaded to descendant Field components. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Gap between fields in the grid. @default 'md' */
+    gap?: Value<ControlSize>;
+    /** Number of explicit grid columns. When > 1, overrides auto-fit behaviour. @default 1 */
+    columns?: Value<number>;
+    /** Minimum field width before columns auto-collapse. @default '15rem' */
+    minFieldWidth?: Value<string>;
+    /** Reduced spacing mode cascaded to descendant Field components. @default false */
+    compact?: Value<boolean>;
+}
+/**
+ * Groups related `Field` components with a shared layout context and optional header.
+ *
+ * Fieldset wraps its children in a `FieldLayout` provider, cascading layout configuration
+ * (layout mode, label width, column count, etc.) to all descendant `Field` components.
+ * Individual fields can still override provider values locally.
+ *
+ * Supports three visual variants (`bordered`, `plain`, `card`) and optional
+ * animated collapse behaviour.
+ *
+ * @example
+ * ```ts
+ * Fieldset(
+ *   {
+ *     legend: 'Personal Information',
+ *     variant: 'bordered',
+ *     layout: 'horizontal-fixed',
+ *     labelWidth: '160px',
+ *     columns: 2,
+ *   },
+ *   Field({ label: 'First Name', content: TextInput({ ... }) }),
+ *   Field({ label: 'Last Name', content: TextInput({ ... }) }),
+ * )
+ * ```
+ */
+export declare function Fieldset({ legend, description, variant, collapsible, defaultCollapsed, disabled, layout, labelWidth, size, gap, columns, minFieldWidth, compact, }: FieldsetOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/form/fieldset/index.d.ts

@@ -0,0 +1 @@
+export * from './fieldset';

package/dist/types/components/form/index.d.ts

@@ -1,5 +1,6 @@
 export * from './control';
 export * from './controller';
+export * from './fieldset';
 export * from './input';
 export * from './schema';
 export * from './use-form';

package/dist/types/components/form/input/combobox-input.d.ts

@@ -81,11 +81,11 @@ export declare const BaseComboboxControl: <T>(options: BaseControlOptions<T, Com
 /**
  * A complete combobox form control with label, description, error message, and validation.
  *
- * Combines {@link BaseComboboxControl} with an {@link InputWrapper} to provide a
+ * Combines {@link BaseComboboxControl} with a {@link Field} to provide a
  * full-featured form field with label, optional description, and validation error display.
  *
  * @template T - The type of the selectable option values
  * @param options - Controller options including wrapper label/description and combobox configuration
  * @returns A combobox input wrapped in a form field with label and error display
  */
-export declare const ComboboxControl: <T>(options: ControlOptions<T, ComboboxInputOptions<T>>) => Renderable;
+export declare const ComboboxControl: <T>(options: ControlOptions<T, ComboboxInputOptions<T>>) => import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/combobox-tags-input.d.ts

@@ -67,4 +67,4 @@ export declare function BaseComboboxTagsControl<T>(options: BaseControlOptions<T
  * @param options - Controller options for the combobox tags control.
  * @returns A renderable form control component with wrapper.
  */
-export declare function ComboboxTagsControl<T>(options: ControlOptions<T[], ComboboxTagsInputOptions<T>>): Renderable;
+export declare function ComboboxTagsControl<T>(options: ControlOptions<T[], ComboboxTagsInputOptions<T>>): import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/date-time-input.d.ts

@@ -24,7 +24,7 @@ import { InputOptions } from './input-options';
  *
  * @example
  * ```ts
- * // With label via InputWrapper
+ * // With label via Field
  * DateTimeInput({
  *   value: prop(new Date()),
  *   onChange: (d) => console.log('Selected:', d.toISOString()),

package/dist/types/components/form/input/dropdown-input.d.ts

@@ -90,11 +90,11 @@ export declare const BaseDropdownControl: <T>(options: BaseControlOptions<T, Dro
 /**
  * A complete dropdown form control with label, description, error message, and validation.
  *
- * Combines {@link BaseDropdownControl} with an {@link InputWrapper} to provide a
+ * Combines {@link BaseDropdownControl} with a {@link Field} to provide a
  * full-featured form field with label, optional description, and validation error display.
  *
  * @template T - The type of the selectable option values
  * @param options - Controller options including wrapper label/description and dropdown configuration
  * @returns A dropdown input wrapped in a form field with label and error display
  */
-export declare const DropdownControl: <T>(options: ControlOptions<T, DropdownInputOptions<T>>) => Renderable;
+export declare const DropdownControl: <T>(options: ControlOptions<T, DropdownInputOptions<T>>) => import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/field-layout.d.ts

@@ -0,0 +1,64 @@
+import { Provider, Value } from '@tempots/dom';
+import type { ControlSize } from '../../theme';
+import type { FieldLabelLayout } from './field';
+/**
+ * Layout configuration values cascaded by the {@link FieldLayout} provider.
+ *
+ * When a `Fieldset` provides this context, descendant `Field` components
+ * automatically inherit these defaults. Local options on individual Fields
+ * take precedence over provider values.
+ */
+export interface FieldLayoutValue {
+    /** Label position relative to input. @default 'vertical' */
+    layout: Value<FieldLabelLayout>;
+    /** Label column width for horizontal layouts. @default '7.5rem' */
+    labelWidth: Value<string>;
+    /** Control size cascaded to children. @default 'md' */
+    size: Value<ControlSize>;
+    /** Gap between fields in a Fieldset. @default 'md' */
+    gap: Value<ControlSize>;
+    /** Number of grid columns. @default 1 */
+    columns: Value<number>;
+    /** Minimum field width before columns auto-collapse. @default '15rem' */
+    minFieldWidth: Value<string>;
+    /** Reduced spacing mode for data-dense interfaces. @default false */
+    compact: Value<boolean>;
+}
+/** Default values for the FieldLayout provider. */
+export declare const FIELD_LAYOUT_DEFAULTS: FieldLayoutValue;
+/**
+ * Options accepted by the {@link FieldLayout} provider.
+ *
+ * All properties are optional — unspecified properties fall back to
+ * {@link FIELD_LAYOUT_DEFAULTS}.
+ */
+export interface FieldLayoutOptions {
+    /** Label position relative to input. @default 'vertical' */
+    layout?: Value<FieldLabelLayout>;
+    /** Label column width for horizontal layouts. @default '7.5rem' */
+    labelWidth?: Value<string>;
+    /** Control size cascaded to children. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Gap between fields in a Fieldset. @default 'md' */
+    gap?: Value<ControlSize>;
+    /** Number of grid columns. @default 1 */
+    columns?: Value<number>;
+    /** Minimum field width before columns auto-collapse. @default '15rem' */
+    minFieldWidth?: Value<string>;
+    /** Reduced spacing mode. @default false */
+    compact?: Value<boolean>;
+}
+/**
+ * Provider that cascades form layout configuration to descendant `Field` components.
+ *
+ * Typically provided by a `Fieldset`, but can also be used directly via `Provide`:
+ *
+ * @example
+ * ```typescript
+ * Provide(FieldLayout, { layout: 'horizontal-fixed', labelWidth: '160px' },
+ *   Field({ label: 'Name', content: TextInput({ ... }) }),
+ *   Field({ label: 'Email', content: TextInput({ ... }) }),
+ * )
+ * ```
+ */
+export declare const FieldLayout: Provider<FieldLayoutValue, any>;

package/dist/types/components/form/input/{input-wrapper.d.ts → field.d.ts}

@@ -2,26 +2,28 @@ import { TNode, Value } from '@tempots/dom';
 /**
  * A visual indicator (asterisk) appended to labels for required fields.
  *
- * Renders as a red asterisk (" *") with the `bc-input-wrapper__required` class.
+ * Renders as a red asterisk (" *") with the `bc-field__required` class.
  */
 export declare const RequiredSymbol: import("@tempots/dom").Renderable;
 /**
- * Layout modes for the input wrapper structure.
+ * Layout modes for the field structure.
  *
  * - `'vertical'` - Label above input (default)
  * - `'horizontal'` - Label and input side-by-side with flexible label width
- * - `'horizontal-label-right'` - Label on the right side of the input
- * - `'horizontal-fixed'` - Label on the left with fixed width (use `labelWidth` option)
+ * - `'horizontal-fixed'` - Label on the left with fixed width, left-aligned
+ * - `'horizontal-end'` - Label on the left with fixed width, right-aligned (flush with input)
+ * - `'horizontal-label-right'` - Label on the right side of the input (for checkboxes, switches)
+ * - `'responsive'` - Horizontal-fixed above 480px, vertical below (container query)
  */
-export type InputWrapperLayout = 'vertical' | 'horizontal' | 'horizontal-label-right' | 'horizontal-fixed';
+export type FieldLabelLayout = 'vertical' | 'horizontal' | 'horizontal-fixed' | 'horizontal-end' | 'horizontal-label-right' | 'responsive';
 /**
- * Configuration options for the `InputWrapper` component.
+ * Configuration options for the `Field` component.
  *
  * This type defines all the options for wrapping an input with label, description,
  * error message, and contextual information. It's used by form controls and
  * standalone inputs to provide consistent labeling and error display.
  */
-export type InputWrapperOptions = {
+export type FieldOptions = {
     /** Whether the wrapper should take full width of its container */
     fullWidth?: Value<boolean>;
     /** Label text or node to display above/beside the input */
@@ -45,9 +47,13 @@ export type InputWrapperOptions = {
     /** Whether the input is disabled (applies disabled styling to label) */
     disabled?: Value<boolean>;
     /** Layout mode for label and input positioning */
-    layout?: Value<InputWrapperLayout>;
-    /** CSS width value for label in 'horizontal-fixed' layout (e.g., '120px', '10rem') */
+    layout?: Value<FieldLabelLayout>;
+    /** CSS width value for label in horizontal layouts (e.g., '120px', '10rem') */
     labelWidth?: Value<string>;
+    /** Reduced spacing mode for data-dense interfaces */
+    compact?: Value<boolean>;
+    /** Number of grid columns this field spans in a Fieldset grid */
+    span?: Value<number>;
 };
 /**
  * Wraps an input element with label, description, error message, and accessibility attributes.
@@ -58,8 +64,9 @@ export type InputWrapperOptions = {
  * - Description text for additional guidance
  * - Error message display with ARIA live region announcements
  * - Proper accessibility attributes (aria-describedby, aria-invalid, role="alert")
- * - Multiple layout modes (vertical, horizontal, horizontal-label-right, horizontal-fixed)
+ * - Multiple layout modes (vertical, horizontal, horizontal-label-right, horizontal-fixed, responsive)
  * - Automatic ID generation for linking label, description, and error to the input
+ * - FieldLayout provider integration: inherits layout settings from a parent Fieldset
  *
  * The component handles state styling (error, disabled) and ensures screen readers
  * receive appropriate context through ARIA attributes.
@@ -73,17 +80,19 @@ export type InputWrapperOptions = {
  * @param options.labelFor - ID of the input element
  * @param options.hasError - Whether to apply error styling
  * @param options.disabled - Whether to apply disabled styling
- * @param options.layout - Layout mode (default: 'vertical')
+ * @param options.layout - Layout mode (default: inherited from FieldLayout or 'vertical')
  * @param options.labelWidth - Fixed width for label in 'horizontal-fixed' layout
+ * @param options.compact - Reduced spacing mode
+ * @param options.span - Number of grid columns this field spans in a Fieldset grid
  * @param options.context - Contextual info in the header (e.g., character count)
  * @param options.labelChildren - Additional content after the label
  * @param options.fullWidth - Whether to take full container width
  * @param children - Additional nodes to append to the wrapper
- * @returns A div element with the complete input wrapper structure
+ * @returns A div element with the complete field structure
  *
  * @example
  * ```ts
- * InputWrapper({
+ * Field({
  *   label: 'Email',
  *   description: 'We will never share your email',
  *   required: true,
@@ -94,4 +103,4 @@ export type InputWrapperOptions = {
  * })
  * ```
  */
-export declare const InputWrapper: ({ fullWidth, required, label, labelChildren, context, description, content, error, labelFor, hasError, disabled, layout, labelWidth, }: InputWrapperOptions, ...children: TNode[]) => import("@tempots/dom").Renderable;
+export declare const Field: (options: FieldOptions, ...children: TNode[]) => import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/index.d.ts

@@ -22,7 +22,8 @@ export * from './files-input';
 export * from './input-adornment';
 export * from './input-container';
 export * from './input-options';
-export * from './input-wrapper';
+export * from './field';
+export * from './field-layout';
 export * from './lazy-native-select';
 export * from './list-input';
 export * from './mask-input';

package/dist/types/components/form/input/multi-select.d.ts

@@ -1,4 +1,4 @@
-import { Renderable, TNode, Value } from '@tempots/dom';
+import { TNode, Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { DropdownOption } from './option';
 import { BaseControlOptions, ControlOptions } from '../control';
@@ -95,4 +95,4 @@ export declare function BaseMultiSelectControl<T>(options: BaseControlOptions<T[
  * @param options - Controller options for the multi-select control.
  * @returns A renderable form control component with wrapper.
  */
-export declare function MultiSelectControl<T>(options: ControlOptions<T[], MultiSelectOptions<T>>): Renderable;
+export declare function MultiSelectControl<T>(options: ControlOptions<T[], MultiSelectOptions<T>>): import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/native-select.d.ts

@@ -59,4 +59,4 @@ export declare function BaseNativeSelectControl<T>(options: BaseControlOptions<T
  * @param options - Controller options for the native select control.
  * @returns A renderable form control component with wrapper.
  */
-export declare function NativeSelectControl<T>(options: ControlOptions<T, NativeSelectOptions<T>>): Renderable;
+export declare function NativeSelectControl<T>(options: ControlOptions<T, NativeSelectOptions<T>>): import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/form/input/range-slider.d.ts

@@ -14,6 +14,17 @@ export interface RangeSliderTick {
     /** Optional label displayed near the tick mark */
     label?: string;
 }
+/**
+ * Definition of a marker dot on the range slider track.
+ * Markers are small circles rendered directly on the track,
+ * unlike ticks which extend outward from the track.
+ */
+export interface RangeSliderMarker {
+    /** The numeric value where this marker appears */
+    value: number;
+    /** Optional label displayed below (horizontal) or beside (vertical) the marker */
+    label?: string;
+}
 /**
  * Style configuration for an individual track segment.
  */
@@ -70,10 +81,16 @@ export interface RangeSliderOptions {
     /** Callback for multi-point mode changes */
     onPointsChange?: (points: number[]) => void;
     /**
-     * Tick marks along the slider track.
+     * Tick marks along the slider track (extend outward from the track).
      * Can be `true` for automatic step-based ticks, or an array of custom tick definitions.
      */
     ticks?: Value<boolean | RangeSliderTick[]>;
+    /**
+     * Marker dots rendered directly on the track surface.
+     * Can be `true` for automatic step-based markers, or an array of custom marker definitions.
+     * Unlike ticks, markers are small circles that sit on the track itself.
+     */
+    markers?: Value<boolean | RangeSliderMarker[]>;
     /**
      * Whether to show the current value label(s) above the thumb(s).
      * @default false
@@ -172,4 +189,4 @@ export interface RangeSliderOptions {
  * )
  * ```
  */
-export declare function RangeSlider({ min: minOpt, max: maxOpt, step: stepOpt, disabled, readonly: readonlyOpt, size, color, value, onChange, range, onRangeChange, points, onPointsChange, ticks, showValue, formatValue, segmentStyles, renderThumb, orientation: orientationOpt, }: RangeSliderOptions): import("@tempots/dom").Renderable;
+export declare function RangeSlider({ min: minOpt, max: maxOpt, step: stepOpt, disabled, readonly: readonlyOpt, size, color, value, onChange, range, onRangeChange, points, onPointsChange, ticks, markers, showValue, formatValue, segmentStyles, renderThumb, orientation: orientationOpt, }: RangeSliderOptions): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/select-tags-input.d.ts

@@ -86,4 +86,4 @@ export declare function BaseSelectTagsControl<T>(options: BaseControlOptions<T[]
  * @param options - Controller options for the select tags control.
  * @returns A renderable form control component with wrapper.
  */
-export declare function SelectTagsControl<T>(options: ControlOptions<T[], SelectTagsInputOptions<T>>): import("@tempots/dom").Renderable;
+export declare function SelectTagsControl<T>(options: ControlOptions<T[], SelectTagsInputOptions<T>>): import("@tempots/core").Renderable<import("@tempots/dom").DOMContext, typeof import("@tempots/dom").DOM_RENDERABLE_TYPE>;

package/dist/types/components/format/format-bigint.d.ts

@@ -0,0 +1,64 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Options for the {@link FormatBigInt} component.
+ *
+ * Separate from FormatNumber because `bigint` values cannot use `percent`,
+ * `compact`, or significant digit options with `Intl.NumberFormat`.
+ */
+export interface FormatBigIntOptions {
+    /** The bigint value to format. @default 9007199254740993 */
+    value: Value<bigint>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Formatting style. @default 'decimal' */
+    style?: Value<'decimal' | 'currency' | 'unit'>;
+    /** ISO 4217 currency code (required when style is 'currency'). @default undefined */
+    currency?: Value<string>;
+    /** How to display the currency. @default 'symbol' */
+    currencyDisplay?: Value<'symbol' | 'narrowSymbol' | 'code' | 'name'>;
+    /** Sign display mode. @default 'auto' */
+    signDisplay?: Value<'auto' | 'never' | 'always' | 'exceptZero'>;
+    /** Unit identifier (e.g., 'kilometer') for style 'unit'. @default undefined */
+    unit?: Value<string>;
+    /** Unit display mode. @default 'short' */
+    unitDisplay?: Value<'short' | 'long' | 'narrow'>;
+    /** Use grouping separators. @default true */
+    useGrouping?: Value<boolean>;
+    /** Minimum integer digits. @default undefined */
+    minimumIntegerDigits?: Value<number>;
+    /** Minimum fraction digits. @default undefined */
+    minimumFractionDigits?: Value<number>;
+    /** Maximum fraction digits. @default undefined */
+    maximumFractionDigits?: Value<number>;
+}
+/**
+ * Formats a bigint value with locale and Intl options.
+ *
+ * @param value - The bigint to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.NumberFormat options
+ * @returns The formatted bigint string
+ *
+ * @example
+ * ```ts
+ * formatBigInt(9007199254740993n, 'en-US') // '9,007,199,254,740,993'
+ * formatBigInt(123456789n, 'en-US', { style: 'currency', currency: 'JPY' }) // '¥123,456,789'
+ * ```
+ */
+export declare function formatBigInt(value: bigint, locale?: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * Locale-aware bigint formatting component.
+ *
+ * Renders a formatted bigint as a `<span>` that automatically updates when
+ * the locale or value changes. Supports decimal, currency, and unit styles.
+ *
+ * @param options - Configuration for the bigint format
+ * @returns A reactive `<span>` containing the formatted bigint
+ *
+ * @example
+ * ```ts
+ * FormatBigInt({ value: 9007199254740993n })
+ * FormatBigInt({ value: 123456789n, style: 'currency', currency: 'JPY' })
+ * ```
+ */
+export declare function FormatBigInt(options: FormatBigIntOptions): TNode;

package/dist/types/components/format/format-date-time.d.ts

@@ -0,0 +1,54 @@
+import { TNode, Value } from '@tempots/dom';
+import type { DateValue, DateFormatStyle } from './format-date';
+import type { TimeFormatStyle } from './format-time';
+/**
+ * Options for the {@link FormatDateTime} component.
+ */
+export interface FormatDateTimeOptions {
+    /** The date/time value to format. @default '2026-03-17T14:30:00' */
+    value: Value<DateValue>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Date portion style. @default 'medium' */
+    dateStyle?: Value<DateFormatStyle>;
+    /** Time portion style. @default 'short' */
+    timeStyle?: Value<TimeFormatStyle>;
+    /** Time zone. @default undefined (browser default) */
+    timeZone?: Value<string>;
+    /** Calendar system. @default undefined */
+    calendar?: Value<string>;
+    /** Whether to use 12-hour time. @default undefined (locale default) */
+    hour12?: Value<boolean>;
+    /** Hour cycle override. @default undefined */
+    hourCycle?: Value<'h11' | 'h12' | 'h23' | 'h24'>;
+}
+/**
+ * Formats a date and time value with locale and Intl options.
+ *
+ * @param value - The date/time value to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.DateTimeFormat options
+ * @returns The formatted date-time string
+ *
+ * @example
+ * ```ts
+ * formatDateTime(new Date(), 'en-US') // 'Mar 17, 2026, 2:30 PM'
+ * ```
+ */
+export declare function formatDateTime(value: DateValue, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Locale-aware date and time formatting component.
+ *
+ * Renders a formatted date-time as a `<span>` that automatically updates when
+ * the locale or value changes.
+ *
+ * @param options - Configuration for the date-time format
+ * @returns A reactive `<span>` containing the formatted date-time
+ *
+ * @example
+ * ```ts
+ * FormatDateTime({ value: new Date() })
+ * FormatDateTime({ value: zonedDateTime, dateStyle: 'full', timeStyle: 'long' })
+ * ```
+ */
+export declare function FormatDateTime(options: FormatDateTimeOptions): TNode;

package/dist/types/components/format/format-date.d.ts

@@ -0,0 +1,82 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Any object with a `toLocaleString` method compatible with `Intl.DateTimeFormat` options.
+ * This covers all Temporal types (PlainDate, PlainDateTime, Instant, ZonedDateTime,
+ * PlainYearMonth, PlainMonthDay) without importing the polyfill.
+ */
+export type TemporalDateLike = {
+    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
+};
+/**
+ * Accepted date value types.
+ * - `Date` — native JavaScript Date
+ * - `string` — ISO 8601 date string
+ * - `number` — Unix timestamp in milliseconds
+ * - `TemporalDateLike` — any Temporal type with `toLocaleString`
+ */
+export type DateValue = Date | string | number | TemporalDateLike;
+/**
+ * Preset date format styles matching `Intl.DateTimeFormat` dateStyle.
+ */
+export type DateFormatStyle = 'full' | 'long' | 'medium' | 'short';
+/**
+ * Options for the {@link FormatDate} component.
+ */
+export interface FormatDateOptions {
+    /** The date value to format. @default '2026-03-17' */
+    value: Value<DateValue>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Date format preset. @default 'medium' */
+    dateStyle?: Value<DateFormatStyle>;
+    /** Calendar system (e.g., 'gregory', 'islamic', 'hebrew'). @default undefined */
+    calendar?: Value<string>;
+    /** Numbering system (e.g., 'arab', 'latn'). @default undefined */
+    numberingSystem?: Value<string>;
+    /** Time zone for date interpretation. @default undefined (browser default) */
+    timeZone?: Value<string>;
+    /** Weekday representation (mutually exclusive with dateStyle). @default undefined */
+    weekday?: Value<'long' | 'short' | 'narrow'>;
+    /** Year representation (mutually exclusive with dateStyle). @default undefined */
+    year?: Value<'numeric' | '2-digit'>;
+    /** Month representation (mutually exclusive with dateStyle). @default undefined */
+    month?: Value<'numeric' | '2-digit' | 'long' | 'short' | 'narrow'>;
+    /** Day representation (mutually exclusive with dateStyle). @default undefined */
+    day?: Value<'numeric' | '2-digit'>;
+    /** Era representation (mutually exclusive with dateStyle). @default undefined */
+    era?: Value<'long' | 'short' | 'narrow'>;
+}
+/**
+ * Formats a date value with locale and Intl options.
+ * Supports native Date, ISO strings, timestamps, and Temporal types.
+ *
+ * @param value - The date value to format
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Intl.DateTimeFormat options
+ * @returns The formatted date string
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date(), 'en-US', { dateStyle: 'full' }) // 'Monday, March 17, 2026'
+ * formatDate('2026-03-17', 'de-DE', { dateStyle: 'short' }) // '17.03.26'
+ * ```
+ */
+export declare function formatDate(value: DateValue, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Locale-aware date formatting component.
+ *
+ * Renders a formatted date as a `<span>` that automatically updates when
+ * the locale or value changes. Supports preset styles, fine-grained part
+ * selection, calendar systems, and Temporal types.
+ *
+ * @param options - Configuration for the date format
+ * @returns A reactive `<span>` containing the formatted date
+ *
+ * @example
+ * ```ts
+ * FormatDate({ value: new Date(), dateStyle: 'full' })
+ * FormatDate({ value: plainDate, dateStyle: 'long' })
+ * FormatDate({ value: '2026-03-17', weekday: 'short', month: 'short', day: 'numeric' })
+ * ```
+ */
+export declare function FormatDate(options: FormatDateOptions): TNode;

package/dist/types/components/format/format-display-name.d.ts

@@ -0,0 +1,70 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Type of display name to resolve.
+ */
+export type DisplayNameType = 'language' | 'region' | 'script' | 'currency' | 'calendar' | 'dateTimeField';
+/**
+ * Format verbosity for display names.
+ */
+export type DisplayNameStyle = 'long' | 'short' | 'narrow';
+/**
+ * Language display style (only for type 'language').
+ */
+export type DisplayNameLanguageDisplay = 'dialect' | 'standard';
+/**
+ * Options for the {@link FormatDisplayName} component.
+ */
+export interface FormatDisplayNameOptions {
+    /** The code to look up (e.g., 'en-US', 'USD', 'Latn'). @default 'en-US' */
+    value: Value<string>;
+    /** The type of display name to resolve. @default 'language' */
+    type: Value<DisplayNameType>;
+    /** BCP 47 locale override. If omitted, uses the Locale provider. @default undefined */
+    locale?: Value<string>;
+    /** Format verbosity. @default 'long' */
+    style?: Value<DisplayNameStyle>;
+    /** Language display style (only for type 'language'). @default 'dialect' */
+    languageDisplay?: Value<DisplayNameLanguageDisplay>;
+    /** Fallback behavior when code is not found. @default 'code' */
+    fallback?: Value<'code' | 'none'>;
+}
+/**
+ * Formats a display name for a language, region, script, currency, calendar,
+ * or dateTimeField code.
+ *
+ * @param value - The code to look up
+ * @param type - The type of display name
+ * @param locale - BCP 47 locale string (uses browser default if omitted)
+ * @param options - Additional display name options
+ * @returns The formatted display name string, or the code itself if not found
+ *
+ * @example
+ * ```ts
+ * formatDisplayName('en-US', 'language', 'en')  // 'American English'
+ * formatDisplayName('USD', 'currency', 'en')    // 'US Dollar'
+ * formatDisplayName('JP', 'region', 'en')       // 'Japan'
+ * ```
+ */
+export declare function formatDisplayName(value: string, type: DisplayNameType, locale?: string, options?: {
+    style?: DisplayNameStyle;
+    languageDisplay?: DisplayNameLanguageDisplay;
+    fallback?: 'code' | 'none';
+}): string;
+/**
+ * Locale-aware display name formatting component.
+ *
+ * Renders the locale-aware name for a language, region, script, currency,
+ * calendar, or dateTimeField code as a `<span>` that automatically updates
+ * when the locale or value changes.
+ *
+ * @param options - Configuration for the display name format
+ * @returns A reactive `<span>` containing the formatted display name
+ *
+ * @example
+ * ```ts
+ * FormatDisplayName({ value: 'en-US', type: 'language' })
+ * FormatDisplayName({ value: 'USD', type: 'currency' })
+ * FormatDisplayName({ value: 'JP', type: 'region' })
+ * ```
+ */
+export declare function FormatDisplayName(options: FormatDisplayNameOptions): TNode;