@juwel-development/design-system 3.7.0 → 3.9.0

package/src/Interaction/MultiSelect/MultiSelectCompositionError.ts

@@ -0,0 +1,6 @@
+export class MultiSelectCompositionError extends Error {
+  constructor(member: string) {
+    super(`MultiSelect.${member} must be composed inside MultiSelect.Root`);
+    this.name = 'MultiSelectCompositionError';
+  }
+}

package/src/Interaction/MultiSelect/fitChips.ts

@@ -0,0 +1,27 @@
+/**
+ * How many leading chips fit on one line beside the hidden-selection count. Every chip fits
+ * when their widths and gaps do; otherwise the count is reserved and the longest prefix that
+ * leaves room for it - and the gap before it - is shown, down to a count-only display.
+ */
+export const fitChips = (
+  chipWidths: readonly number[],
+  countWidth: number,
+  availableWidth: number,
+  gap: number,
+): number => {
+  const gaps = Math.max(chipWidths.length - 1, 0) * gap;
+  const total = chipWidths.reduce((sum, width) => sum + width, 0) + gaps;
+  if (total <= availableWidth) {
+    return chipWidths.length;
+  }
+  let visible = 0;
+  let used = countWidth;
+  for (const width of chipWidths) {
+    if (used + width + gap > availableWidth) {
+      break;
+    }
+    used += width + gap;
+    visible += 1;
+  }
+  return visible;
+};

package/src/Interaction/NumberInput/NumberInput.tsx

@@ -0,0 +1,125 @@
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, useEffect, useId, useRef } from 'react';
+import type { Subject } from 'rxjs';
+
+// One recipe of its own, not Input's (design-system-components.md §4, issue #111): a text control
+// so `-`, `1.` and `1,5` survive - the Number state sanitises them to `''` (WHATWG input.html
+// #number-state) - with `inputmode=decimal` as a keyboard hint only. The classes are Input's, for
+// Input's reasons: tokens re-pointed by `.dark`, the ring of docs/adr/0002, the faces of 0004.
+const numberInput = cva(
+  'block w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
+);
+
+export interface INumberInputProps {
+  /** Always rendered and associated with the control; never replaced by the placeholder. */
+  label: string;
+  /** How the surrounding form reads the entered text on submit. */
+  name: string;
+  /** Presence only: the form rejects an empty field, never a non-numeric one. */
+  required?: boolean;
+  /** How a non-required field says so, in the consuming app's language; left out, no marker renders. */
+  optionalLabel?: string;
+  hint?: string;
+  /** The consumer's verdict on the text; the control renders it and keeps accepting edits. */
+  invalid?: boolean;
+  errorMessage?: string;
+  disabled?: boolean;
+  placeholder?: string;
+  /**
+   * Initialises the uncontrolled field, on mount only: a later change never replaces the current
+   * edit. To restore saved text, remount the field with it; native form reset returns to it.
+   */
+  defaultValue?: string;
+  /** Emits the current text on every user edit - typing, pasting, clearing - and on nothing else. */
+  onInput$?: Subject<string>;
+  /** Emit to empty the control in place, keeping the same node so focus survives; `onInput$` stays silent. */
+  reset$?: Subject<void>;
+  testId?: string;
+}
+
+/**
+ * A labelled field for typing numeric amounts and thresholds. It is a text control with a decimal
+ * keyboard hint, so the entered text - blank, `0`, `-`, `1.`, `1,5` or pasted content - is kept
+ * exactly as typed and read by the form by `name`. Parsing, locale and validity are the consumer's.
+ */
+export const NumberInput: FunctionComponent<INumberInputProps> = ({
+  label,
+  name,
+  required,
+  optionalLabel,
+  hint,
+  invalid,
+  errorMessage,
+  disabled,
+  placeholder,
+  defaultValue,
+  onInput$,
+  reset$,
+  testId,
+}) => {
+  const id = useId();
+  const controlId = `${id}-control`;
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+  const describedBy =
+    [hint ? hintId : undefined, invalid ? errorId : undefined]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  // reset$ is the one inbound command, so the component subscribes here (coding.md#asynchrony) and
+  // owns the teardown; onInput$ it only emits on. Emptying the live node keeps focus and any
+  // in-flight IME composition, which a `key` remount would discard (issue #64).
+  const controlRef = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    const subscription = reset$?.subscribe(() => {
+      if (controlRef.current) {
+        controlRef.current.value = '';
+      }
+    });
+    return () => subscription?.unsubscribe();
+  }, [reset$]);
+
+  return (
+    <div className={'flex flex-col gap-[var(--space-stack)]'}>
+      <label
+        htmlFor={controlId}
+        className={'font-secondary font-medium text-body text-foreground'}
+      >
+        {label}
+      </label>
+      <input
+        ref={controlRef}
+        id={controlId}
+        name={name}
+        type={'text'}
+        inputMode={'decimal'}
+        className={numberInput()}
+        required={required}
+        disabled={disabled}
+        defaultValue={defaultValue}
+        placeholder={placeholder}
+        aria-invalid={invalid || undefined}
+        aria-describedby={describedBy}
+        data-testid={testId}
+        onInput={(event) =>
+          !disabled && onInput$?.next(event.currentTarget.value)
+        }
+      />
+      {!required && optionalLabel && (
+        <span className={'font-secondary text-muted text-small'}>
+          {optionalLabel}
+        </span>
+      )}
+      {hint && (
+        <p id={hintId} className={'font-secondary text-muted text-small'}>
+          {hint}
+        </p>
+      )}
+      {invalid && (
+        <p id={errorId} className={'font-secondary text-error text-small'}>
+          {errorMessage}
+        </p>
+      )}
+    </div>
+  );
+};

package/src/Interaction/Select/Select.tsx

@@ -0,0 +1,140 @@
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, type ReactNode, useId } from 'react';
+import type { Subject } from 'rxjs';
+
+// Field styling follows Input and ADRs 0001–0004; native appearance retains the platform picker.
+const selectRoot = cva(
+  [
+    'flex flex-col gap-[var(--space-stack)]',
+    '[&>label]:font-secondary [&>label]:font-medium [&>label]:text-body [&>label]:text-foreground',
+    '[&>span]:font-secondary [&>span]:text-muted [&>span]:text-small',
+    '[&>p]:font-secondary [&>p]:text-small [&>p]:text-muted [&>p[data-error]]:text-error',
+    '[&>select]:block [&>select]:w-full [&>select]:rounded-[var(--radius-control)] [&>select]:border [&>select]:border-solid [&>select]:border-control-border [&>select]:bg-transparent [&>select]:px-3 [&>select]:py-2',
+    '[&>select]:font-primary [&>select]:text-body [&>select]:text-foreground [&>select]:transition-colors [&>select]:duration-[var(--motion-duration-color)]',
+    '[&>select]:outline-focus-ring [&>select]:outline-offset-[var(--focus-ring-offset)] [&>select]:focus-visible:outline [&>select]:focus-visible:outline-[length:var(--focus-ring-width)]',
+    '[&>select:user-invalid]:border-error [&>select]:aria-[invalid=true]:border-error [&>select]:disabled:cursor-not-allowed [&>select]:disabled:border-disabled [&>select]:disabled:text-muted',
+  ].join(' '),
+);
+
+export interface ISelectRootProps {
+  /** Always rendered and associated with the control. */
+  label: string;
+  /** How the surrounding form reads the value on submit. */
+  name: string;
+  required?: boolean;
+  /** Caller-localized marker, rendered only when the field is optional. */
+  optionalLabel?: string;
+  disabled?: boolean;
+  invalid?: boolean;
+  hint?: string;
+  errorMessage?: string;
+  testId?: string;
+  /** Initial selection only; omitted or unmatched values start empty. */
+  defaultValue?: string;
+  /** Emits the selected value only on user changes; never on render or native form reset. */
+  onChange$?: Subject<string>;
+  /** Caller-localized wording for the first, empty option, which remains selectable. */
+  placeholder: string;
+  /** Compose Select.Option children; arrays, fragments and consumer components are supported. */
+  children?: ReactNode;
+}
+
+/**
+ * An uncontrolled native single-select field. The first option is always empty and selectable;
+ * `required` makes that empty value invalid. Option updates preserve a surviving selected value
+ * and fall back to empty when it disappears, without emitting. The form reads the value by name.
+ */
+const SelectRoot: FunctionComponent<ISelectRootProps> = ({
+  label,
+  name,
+  required,
+  optionalLabel,
+  disabled,
+  invalid,
+  hint,
+  errorMessage,
+  testId,
+  defaultValue,
+  onChange$,
+  placeholder,
+  children,
+}) => {
+  const id = useId();
+  const controlId = `${id}-control`;
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+  const describedBy =
+    [hint ? hintId : undefined, invalid && errorMessage ? errorId : undefined]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  return (
+    <div className={selectRoot()}>
+      <label htmlFor={controlId}>{label}</label>
+      <select
+        id={controlId}
+        name={name}
+        required={required}
+        disabled={disabled}
+        defaultValue={defaultValue ?? ''}
+        aria-invalid={invalid || undefined}
+        aria-describedby={describedBy}
+        data-testid={testId}
+        onChange={(event) =>
+          !disabled && onChange$?.next(event.currentTarget.value)
+        }
+      >
+        <option value={''}>{placeholder}</option>
+        {children}
+      </select>
+      {!required && optionalLabel && <span>{optionalLabel}</span>}
+      {hint && <p id={hintId}>{hint}</p>}
+      {invalid && errorMessage && (
+        <p id={errorId} data-error>
+          {errorMessage}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export interface ISelectOptionProps {
+  /** Unique, stable, nonempty identity; the empty string belongs to Root's placeholder. */
+  value: string;
+  /** Caller-localized text; native options do not accept rich content. */
+  children: string;
+  testId?: string;
+}
+
+const SelectOption: FunctionComponent<ISelectOptionProps> = ({
+  value,
+  children,
+  testId,
+}) => (
+  <option value={value} data-testid={testId}>
+    {children}
+  </option>
+);
+
+/**
+ * An uncontrolled native single-select field composed from Root and Option.
+ * Root owns the label, selectable empty placeholder and field messages; Option renders text.
+ *
+ * @Guarantees
+ * - Required rejects empty; forms read the current stable value by name.
+ * - onChange$ emits user changes (including clearing), never rendering, option updates or reset.
+ * - Omitted/unmatched defaults start empty; later defaultValue changes do not select a value.
+ * - Removing the selected option falls back to empty without emitting.
+ *
+ * @CallerMustEnsure
+ * - Compose Option members under Root; arrays, fragments and consumer components are supported.
+ * - Option values are unique, stable and nonempty, with stable React keys when mapping children.
+ * - The consumer owns all wording, stream lifetime and domain reconciliation on updates/reset.
+ * - Native reset restores the original default while its option stays mounted, otherwise empty.
+ *   A newly mounted option does not inherit a removed option's reset default; remount Root to
+ *   initialize another record. Translation/reordering with stable keys preserves native state.
+ */
+export const Select = {
+  Root: SelectRoot,
+  Option: SelectOption,
+} as const;

package/src/index.ts

@@ -24,6 +24,9 @@ export { Button } from 'Interaction/Button/Button';
 export { Choices } from 'Interaction/Choices/Choices';
 export { Input } from 'Interaction/Input/Input';
 export { Link } from 'Interaction/Link/Link';
+export { MultiSelect } from 'Interaction/MultiSelect/MultiSelect';
+export { NumberInput } from 'Interaction/NumberInput/NumberInput';
+export { Select } from 'Interaction/Select/Select';
 export { Slider } from 'Interaction/Slider/Slider';
 export { Tabs } from 'Interaction/Tabs/Tabs';
 export { TextArea } from 'Interaction/TextArea/TextArea';