sheer-ui 0.0.0

package/src/lib/components/time-field/types.ts

@@ -0,0 +1,174 @@
+import type { Time } from "@internationalized/date";
+import type { EditableSegmentPart, WithChildren } from "../../internal/index.js";
+import type { OnChangeFn, WithChild, Without } from "../../internal/types.js";
+import type {
+	BitsPrimitiveDivAttributes,
+	BitsPrimitiveSpanAttributes,
+} from "../../internal/attribute-types.js";
+import type {
+	TimeGranularity,
+	TimeOnInvalid,
+	TimeSegmentPart,
+	TimeValidator,
+	TimeValue,
+} from "../../internal/date-time/types.js";
+
+export type TimeFieldRootPropsWithoutHTML<T extends TimeValue = Time> = WithChildren<{
+	/**
+	 * The value of the time field.
+	 *
+	 * @bindable
+	 */
+	value?: T;
+
+	/**
+	 * A callback that is called when the time field value changes.
+	 *
+	 */
+	onValueChange?: OnChangeFn<T | undefined>;
+
+	/**
+	 * The placeholder value of the time field. This determines the format
+	 * and what time the field starts at when it is empty.
+	 *
+	 * @bindable
+	 */
+	placeholder?: TimeValue;
+
+	/**
+	 * A callback that is called when the time field's placeholder value changes.
+	 */
+	onPlaceholderChange?: OnChangeFn<TimeValue | undefined>;
+
+	/**
+	 * A function that returns a string or array of strings as validation errors if the time is
+	 * invalid, or nothing if the time is valid
+	 */
+	validate?: TimeValidator<T>;
+
+	/**
+	 * A callback fired when the time field's value is invalid. Use this to display an error
+	 * message to the user.
+	 */
+	onInvalid?: TimeOnInvalid;
+
+	/**
+	 * The minimum acceptable time. When provided, the time field
+	 * will be marked as invalid if the user enters a time before this time.
+	 */
+	minValue?: TimeValue;
+
+	/**
+	 * The maximum acceptable time. When provided, the time field
+	 * will be marked as invalid if the user enters a time after this time.
+	 */
+	maxValue?: TimeValue;
+
+	/**
+	 * If true, the time field will be disabled and users will not be able
+	 * to interact with it. This also disables the hidden input element if
+	 * the time field is used in a form.
+	 *
+	 * @defaultValue false
+	 */
+	disabled?: boolean;
+
+	/**
+	 * If true, the time field will be readonly, and users will not be able to
+	 * edit the values of any of the individual segments.
+	 *
+	 * @defaultValue false
+	 */
+	readonly?: boolean;
+
+	/**
+	 * An array of segment names that should be readonly. If provided, only the
+	 * segments not in this array will be editable.
+	 */
+	readonlySegments?: EditableSegmentPart[];
+
+	/**
+	 * The format to use for displaying the time in the input.
+	 * If using a 12 hour clock, ensure you also include the `dayPeriod`
+	 * segment in your input to ensure the user can select AM/PM.
+	 *
+	 * @defaultValue the locale's default time format
+	 */
+	hourCycle?: 12 | 24;
+
+	/**
+	 * The locale to use for formatting the time field.
+	 *
+	 * @defaultValue 'en'
+	 */
+	locale?: string;
+
+	/**
+	 * The granularity of the time field. This determines which
+	 * segments will be includes in the segments array used to
+	 * build the time field.
+	 *
+	 * Granularity is only used for visual purposes, and does not impact
+	 * the value of the time field. You can have the same value synced
+	 * between multiple time fields with different granularities and they
+	 * will all contain the same value.
+	 *
+	 * @default 'minute'
+	 */
+	granularity?: TimeGranularity;
+
+	/**
+	 * Whether or not to hide the timeZoneName segment from the time field.
+	 *
+	 * @default false;
+	 */
+	hideTimeZone?: boolean;
+
+	/**
+	 * Whether or not the hidden input of the time field requires a value
+	 * to be submitted.
+	 *
+	 * @defaultValue false
+	 */
+	required?: boolean;
+
+	/**
+	 * The `id` of the element which contains the error messages for the time field when the
+	 * time is invalid.
+	 */
+	errorMessageId?: string;
+}>;
+
+export type TimeFieldRootProps<T extends TimeValue = Time> = TimeFieldRootPropsWithoutHTML<T>;
+
+export type TimeFieldInputSnippetProps = {
+	segments: Array<{ part: TimeSegmentPart; value: string }>;
+};
+
+export type TimeFieldInputPropsWithoutHTML = WithChild<
+	{
+		/**
+		 * The name to use for the hidden input element of the time field,
+		 * which is used to submit the ISO string value of the time field
+		 * to a server. If not provided, the hidden input element will not
+		 * be rendered.
+		 */
+		name?: string;
+	},
+	TimeFieldInputSnippetProps
+>;
+
+export type TimeFieldInputProps = TimeFieldInputPropsWithoutHTML &
+	Without<BitsPrimitiveDivAttributes, TimeFieldInputPropsWithoutHTML>;
+
+export type TimeFieldSegmentPropsWithoutHTML = WithChild<{
+	part: TimeSegmentPart;
+}>;
+
+export type TimeFieldSegmentProps = TimeFieldSegmentPropsWithoutHTML &
+	Without<BitsPrimitiveSpanAttributes, TimeFieldSegmentPropsWithoutHTML>;
+
+export type TimeFieldLabelPropsWithoutHTML = WithChild;
+
+export type TimeFieldLabelProps = TimeFieldLabelPropsWithoutHTML &
+	Without<BitsPrimitiveDivAttributes, TimeFieldLabelPropsWithoutHTML>;

package/src/lib/components/time-range-field/components/time-range-field-input.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import type { TimeRangeFieldInputProps } from '../types.js';
+	import { TimeRangeFieldInputState } from '../time-range-field.svelte.js';
+	import { createId } from '../../../internal/create-id.js';
+	import TimeFieldHiddenInput from '../../time-field/components/time-field-hidden-input.svelte';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), ref = $bindable(null), name = '', child, children, type, ...restProps }: TimeRangeFieldInputProps = $props();
+
+	const inputState = TimeRangeFieldInputState.create(
+		{
+			id: boxWith(() => id),
+			ref: boxWith(
+				() => ref,
+				(v) => (ref = v),
+			),
+			name: boxWith(() => name),
+		},
+		type,
+	);
+
+	const mergedProps = $derived(mergeProps(restProps, inputState.props, { role: 'presentation' }));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps, segments: inputState.root.segmentContents })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.({ segments: inputState.root.segmentContents })}
+	</div>
+{/if}
+
+<TimeFieldHiddenInput />

package/src/lib/components/time-range-field/components/time-range-field-label.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { TimeRangeFieldLabelState } from '../time-range-field.svelte.js';
+	import type { TimeRangeFieldLabelProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), ref = $bindable(null), children, child, ...restProps }: TimeRangeFieldLabelProps = $props();
+
+	const labelState = TimeRangeFieldLabelState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, labelState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<span {...mergedProps}>
+		{@render children?.()}
+	</span>
+{/if}

package/src/lib/components/time-range-field/components/time-range-field.svelte

@@ -0,0 +1,104 @@
+<script lang="ts" module>
+	import type { TimeEndpoints, TimeValue } from '../../../internal/date-time/types.js';
+	import type { Time } from '@internationalized/date';
+</script>
+
+<script lang="ts" generics="T extends TimeValue = Time">
+	import { boxWith, repairBindable } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { TimeRangeFieldRootState } from '../time-range-field.svelte.js';
+	import type { TimeRangeFieldRootProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+	import { getDefaultTime } from '../../../internal/date-time/utils.js';
+	import { resolveLocaleProp } from '../../../internal/prop-resolvers.js';
+
+	const uid = $props.id();
+
+	let {
+		id = createId(uid),
+		ref = $bindable(null),
+		value = $bindable(),
+		onValueChange = () => {},
+		placeholder = $bindable(),
+		onPlaceholderChange = () => {},
+		disabled = false,
+		readonly = false,
+		required = false,
+		hourCycle,
+		granularity,
+		locale,
+		hideTimeZone = false,
+		validate = () => {},
+		onInvalid = () => {},
+		maxValue,
+		minValue,
+		readonlySegments = [],
+		children,
+		child,
+		errorMessageId,
+		...restProps
+	}: TimeRangeFieldRootProps<T> = $props();
+
+	function repairUndefinedControlledPlaceholder() {
+		if (placeholder !== undefined) return;
+		const defaultPlaceholder = getDefaultTime({ granularity, defaultValue: value?.start });
+		placeholder = defaultPlaceholder;
+	}
+
+	// TimeRangeField needs a writable placeholder for segment state.
+	repairBindable(() => placeholder, repairUndefinedControlledPlaceholder);
+
+	function repairUndefinedControlledValue() {
+		if (value !== undefined) return;
+		const defaultValue = { start: undefined, end: undefined };
+		value = defaultValue;
+	}
+
+	// Range field state owns a TimeEndpoints object, even when empty.
+	repairBindable(() => value, repairUndefinedControlledValue);
+
+	const rootState = TimeRangeFieldRootState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+		disabled: boxWith(() => disabled),
+		readonly: boxWith(() => readonly),
+		required: boxWith(() => required),
+		hourCycle: boxWith(() => hourCycle),
+		granularity: boxWith(() => granularity),
+		locale: resolveLocaleProp(() => locale),
+		hideTimeZone: boxWith(() => hideTimeZone),
+		validate: boxWith(() => validate),
+		maxValue: boxWith(() => maxValue),
+		minValue: boxWith(() => minValue),
+		placeholder: boxWith(
+			() => placeholder as TimeValue,
+			(v) => {
+				placeholder = v;
+				onPlaceholderChange(v);
+			},
+		),
+		readonlySegments: boxWith(() => readonlySegments),
+		value: boxWith(
+			() => value as TimeEndpoints<T>,
+			(v) => {
+				value = v;
+				onValueChange(v);
+			},
+		),
+		onInvalid: boxWith(() => onInvalid),
+		errorMessageId: boxWith(() => errorMessageId),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, rootState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.()}
+	</div>
+{/if}

package/src/lib/components/time-range-field/index.ts

@@ -0,0 +1,11 @@
+export { default as Root } from './components/time-range-field.svelte';
+export { default as Input } from './components/time-range-field-input.svelte';
+export { default as Label } from './components/time-range-field-label.svelte';
+export { default as Segment } from '../time-field/components/time-field-segment.svelte';
+
+export type {
+	TimeRangeFieldRootProps as RootProps,
+	TimeRangeFieldLabelProps as LabelProps,
+	TimeRangeFieldInputProps as InputProps,
+	TimeRangeFieldSegmentProps as SegmentProps,
+} from './types.js';

package/src/lib/components/time-range-field/time-range-field.svelte.ts

@@ -0,0 +1,235 @@
+import type { Time } from '@internationalized/date';
+import { boxWith, attachRef, DOMContext, type ReadableBoxedValues, type WritableBoxedValues } from '../../internal/tools/index.js';
+import { createContext, onMount } from 'svelte';
+import { TimeFieldRootState } from '../time-field/time-field.svelte.js';
+import { TimeFieldInputState } from '../time-field/time-field.svelte.js';
+import { createId } from '../../internal/create-id.js';
+import type { TimeSegmentPart } from '../../internal/index.js';
+import type { RefAttachment, WithRefOpts } from '../../internal/types.js';
+import { createBitsAttrs, boolToEmptyStrOrUndef } from '../../internal/attrs.js';
+import type { TimeGranularity, TimeOnInvalid, TimeEndpoints, TimeRangeValidator, TimeValue } from '../../internal/date-time/types.js';
+import { type TimeFormatter, createTimeFormatter } from '../../internal/date-time/formatter.js';
+import { getFirstSegment } from '../../internal/date-time/field/segments.js';
+import { convertTimeValueToTime, isTimeBefore } from '../../internal/date-time/field/time-helpers.js';
+import { RangeFieldValueController } from '../../internal/date-time/field/range-field.svelte.js';
+
+export const timeRangeFieldAttrs = createBitsAttrs({
+	component: 'time-range-field',
+	parts: ['root', 'label'],
+});
+
+export const [getTimeRangeFieldRoot, setTimeRangeFieldRoot] = createContext<TimeRangeFieldRootState>();
+
+interface TimeRangeFieldRootStateOpts<T extends TimeValue = Time>
+	extends
+		WithRefOpts,
+		WritableBoxedValues<{
+			value: TimeEndpoints<T>;
+			placeholder: TimeValue;
+		}>,
+		ReadableBoxedValues<{
+			readonlySegments: TimeSegmentPart[];
+			validate: TimeRangeValidator<T> | undefined;
+			onInvalid: TimeOnInvalid | undefined;
+			minValue: TimeValue | undefined;
+			maxValue: TimeValue | undefined;
+			disabled: boolean;
+			readonly: boolean;
+			granularity: TimeGranularity | undefined;
+			hourCycle: 12 | 24 | undefined;
+			locale: string;
+			hideTimeZone: boolean;
+			required: boolean;
+			errorMessageId: string | undefined;
+		}> {}
+
+export class TimeRangeFieldRootState<T extends TimeValue = Time> {
+	static create<T extends TimeValue = Time>(opts: TimeRangeFieldRootStateOpts<T>) {
+		return setTimeRangeFieldRoot(new TimeRangeFieldRootState(opts) as unknown as TimeRangeFieldRootState);
+	}
+	readonly opts: TimeRangeFieldRootStateOpts<T>;
+	readonly attachment: RefAttachment;
+	startFieldState: TimeFieldRootState | undefined = undefined;
+	endFieldState: TimeFieldRootState | undefined = undefined;
+	descriptionId: string;
+	formatter: TimeFormatter;
+	fieldNode = $state<HTMLElement | null>(null);
+	labelNode = $state<HTMLElement | null>(null);
+	descriptionNode = $state<HTMLElement | null>(null);
+	readonly valueController: RangeFieldValueController<T>;
+	get startValue() { return this.valueController.start; }
+	get endValue() { return this.valueController.end; }
+	get startValueComplete() { return this.valueController.startComplete; }
+	get endValueComplete() { return this.valueController.endComplete; }
+	get rangeComplete() { return this.valueController.complete; }
+
+	readonly startValueTime = $derived.by(() => {
+		if (!this.startValue) return undefined;
+		return convertTimeValueToTime(this.startValue);
+	});
+
+	readonly endValueTime = $derived.by(() => {
+		if (!this.endValue) return undefined;
+		return convertTimeValueToTime(this.endValue);
+	});
+
+	readonly minValueTime = $derived.by(() => {
+		if (!this.opts.minValue.current) return undefined;
+		return convertTimeValueToTime(this.opts.minValue.current);
+	});
+
+	readonly maxValueTime = $derived.by(() => {
+		if (!this.opts.maxValue.current) return undefined;
+		return convertTimeValueToTime(this.opts.maxValue.current);
+	});
+	domContext: DOMContext;
+
+	constructor(opts: TimeRangeFieldRootStateOpts<T>) {
+		this.opts = opts;
+		this.descriptionId = createId('description', opts.id.current);
+		this.valueController = new RangeFieldValueController(
+			opts.value,
+			boxWith(
+				() => opts.placeholder.current as T,
+				(value) => (opts.placeholder.current = value),
+			),
+		);
+		this.formatter = createTimeFormatter(this.opts.locale.current);
+		this.domContext = new DOMContext(this.opts.ref);
+		this.attachment = attachRef(this.opts.ref, (v) => (this.fieldNode = v));
+		onMount(() => () => {
+			this.domContext.getDocument().getElementById(this.descriptionId)?.remove();
+		});
+
+		$effect(() => {
+			if (this.formatter.getLocale() === this.opts.locale.current) return;
+			this.formatter.setLocale(this.opts.locale.current);
+		});
+	}
+
+	/** Box for a child field's value: reads the derived side; writes override it and recommit the range. */
+	sideValueBox(type: 'start' | 'end') {
+		return this.valueController.sideValueBox(type);
+	}
+
+	readonly validationStatus = $derived.by(() => {
+		const value = this.opts.value.current;
+		if (value === undefined) return false as const;
+		if (value.start === undefined || value.end === undefined) return false as const;
+
+		const msg = this.opts.validate.current?.({
+			start: value.start,
+			end: value.end,
+		});
+
+		if (msg) {
+			return {
+				reason: 'custom',
+				message: msg,
+			} as const;
+		}
+
+		if (this.minValueTime && this.startValueTime && isTimeBefore(this.startValueTime, this.minValueTime)) {
+			return {
+				reason: 'min',
+			} as const;
+		}
+
+		if (this.maxValueTime && this.endValueTime && isTimeBefore(this.maxValueTime, this.endValueTime)) {
+			return {
+				reason: 'max',
+			} as const;
+		}
+
+		return false as const;
+	});
+
+	readonly isInvalid = $derived(this.validationStatus !== false);
+
+	props = $derived.by(
+		() =>
+			({
+				id: this.opts.id.current,
+				role: 'group',
+				[timeRangeFieldAttrs.root]: '',
+				'data-invalid': boolToEmptyStrOrUndef(this.isInvalid),
+				...this.attachment,
+			}) as const,
+	);
+}
+
+interface TimeRangeFieldLabelStateOpts extends WithRefOpts {}
+
+export class TimeRangeFieldLabelState {
+	static create(opts: TimeRangeFieldLabelStateOpts) {
+		return new TimeRangeFieldLabelState(opts, getTimeRangeFieldRoot());
+	}
+	readonly opts: TimeRangeFieldLabelStateOpts;
+	readonly root: TimeRangeFieldRootState;
+	readonly attachment: RefAttachment;
+
+	constructor(opts: TimeRangeFieldLabelStateOpts, root: TimeRangeFieldRootState) {
+		this.opts = opts;
+		this.root = root;
+		this.attachment = attachRef(this.opts.ref, (v) => (this.root.labelNode = v));
+	}
+
+	#onclick = () => {
+		if (this.root.opts.disabled.current) return;
+		const firstSegment = getFirstSegment(this.root.fieldNode);
+		if (!firstSegment) return;
+		firstSegment.focus();
+	};
+
+	readonly props = $derived.by(
+		() =>
+			({
+				id: this.opts.id.current,
+				'data-invalid': boolToEmptyStrOrUndef(this.root.isInvalid),
+				'data-disabled': boolToEmptyStrOrUndef(this.root.opts.disabled.current),
+				[timeRangeFieldAttrs.label]: '',
+				onclick: this.#onclick,
+				...this.attachment,
+			}) as const,
+	);
+}
+
+interface TimeRangeFieldInputStateOpts<T extends TimeValue = Time>
+	extends
+		WritableBoxedValues<{
+			value: T | undefined;
+		}>,
+		ReadableBoxedValues<{
+			name: string;
+		}>,
+		WithRefOpts {}
+
+export class TimeRangeFieldInputState {
+	static create(opts: Omit<TimeRangeFieldInputStateOpts, 'value'>, type: 'start' | 'end') {
+		const root = getTimeRangeFieldRoot();
+		const fieldState = TimeFieldRootState.create(
+			{
+				value: root.sideValueBox(type),
+				disabled: root.opts.disabled,
+				readonly: root.opts.readonly,
+				readonlySegments: root.opts.readonlySegments,
+				validate: boxWith(() => undefined),
+				minValue: root.opts.minValue,
+				maxValue: root.opts.maxValue,
+				hourCycle: root.opts.hourCycle,
+				locale: root.opts.locale,
+				hideTimeZone: root.opts.hideTimeZone,
+				required: root.opts.required,
+				granularity: root.opts.granularity,
+				placeholder: root.opts.placeholder,
+				onInvalid: root.opts.onInvalid,
+				errorMessageId: root.opts.errorMessageId,
+				isInvalidProp: boxWith(() => root.isInvalid),
+				descriptionId: createId(`${type}-description`, root.opts.id.current),
+			},
+			root,
+		);
+
+		return new TimeFieldInputState({ name: opts.name, id: opts.id, ref: opts.ref }, fieldState);
+	}
+}