@mlola-ui/registry 1.0.0

package/snapshot/source/packages/components/textarea/textarea.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import * as React from "react";
+import { composeRefs, cx } from "../_internal/react";
+import { Field, fieldDescription } from "../input/input";
+
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: string;
+  hint?: string;
+  error?: string;
+  /** Grow with the text up to this many rows, then scroll. */
+  maxRows?: number;
+  /** Show a live character count against `maxLength`. */
+  showCount?: boolean;
+  containerClassName?: string;
+}
+
+/**
+ * Multi-line text that grows as it is written. With a `maxLength`, a counter
+ * appears near the limit and turns to the danger colour past it.
+ */
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ label, hint, error, maxRows = 12, showCount = false, containerClassName, className, id, disabled, required, rows = 3, maxLength, onChange, value, defaultValue, style, "aria-describedby": describedBy, ...props }, ref) => {
+    const generated = React.useId();
+    const fieldId = id ?? `textarea-${generated}`;
+    const node = React.useRef<HTMLTextAreaElement>(null);
+    const [length, setLength] = React.useState(() => String(value ?? defaultValue ?? "").length);
+    const current = value !== undefined ? String(value).length : length;
+
+    const resize = React.useCallback(() => {
+      const element = node.current;
+      if (!element || CSS.supports?.("field-sizing", "content")) return;
+      element.style.height = "auto";
+      element.style.height = `${element.scrollHeight}px`;
+    }, []);
+    React.useLayoutEffect(resize, [resize, value]);
+
+    const near = maxLength !== undefined && (showCount || current > maxLength * 0.8);
+    return (
+      <Field id={fieldId} label={label} hint={hint} error={error} required={required} disabled={disabled} className={containerClassName}>
+        <textarea
+          ref={composeRefs(ref, node)}
+          id={fieldId}
+          rows={rows}
+          disabled={disabled}
+          required={required}
+          maxLength={maxLength}
+          value={value}
+          defaultValue={defaultValue}
+          aria-invalid={error ? true : undefined}
+          aria-describedby={fieldDescription(fieldId, { hint, error, describedBy })}
+          className={cx("ml-textarea", className)}
+          style={{ ...style, ["--ml-textarea-max-rows" as string]: maxRows }}
+          onChange={(event) => {
+            setLength(event.target.value.length);
+            resize();
+            onChange?.(event);
+          }}
+          {...props}
+        />
+        {near ? (
+          <p className="ml-textarea-count" data-full={current >= (maxLength ?? Infinity) || undefined} aria-live="polite">
+            {current} / {maxLength}
+          </p>
+        ) : null}
+      </Field>
+    );
+  },
+);
+Textarea.displayName = "Textarea";

package/snapshot/source/packages/components/time-picker/time-picker.tsx

@@ -0,0 +1,286 @@
+"use client";
+
+import * as React from "react";
+import { IconClock } from "@mlola-ui/icons";
+import { Field, fieldDescription } from "../input/input";
+import { Popover } from "../popover/popover";
+import { cx } from "../_internal/react";
+import { fromMinutes, isTimeAllowed, nearestAllowed, nextAllowed, toMinutes, type TimeMatchers, type TimeRules } from "./times";
+
+export type { TimeMatcher, TimeMatchers } from "./times";
+export { isTimeAllowed, matchesTime } from "./times";
+
+export interface TimePickerProps {
+  label?: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  /** "HH:MM", 24-hour. */
+  value?: string | null;
+  defaultValue?: string | null;
+  onValueChange?: (value: string | null) => void;
+  /** 12 or 24; by default the locale decides. */
+  hourCycle?: 12 | 24;
+  /** Minutes the arrow keys move by. */
+  step?: number;
+  /** Minutes between times in the quick list. */
+  listStep?: number;
+  min?: string;
+  max?: string;
+  /**
+   * Times that cannot be picked: "HH:MM", a range "12:00-13:00", `{ from, to }`
+   * or a function. Ranges include their start and exclude their end, so
+   * 13:00 is free again after a 12:00-13:00 break.
+   */
+  disabledTimes?: TimeMatchers;
+  /** When given, only these times can be picked, such as bookable slots; same forms as `disabledTimes`. */
+  enabledTimes?: TimeMatchers;
+  locale?: string;
+  disabled?: boolean;
+  required?: boolean;
+  id?: string;
+  className?: string;
+}
+
+const pad = (value: number) => String(value).padStart(2, "0");
+const wrap = (value: number, size: number) => ((value % size) + size) % size;
+
+type Segment = "hour" | "minute" | "period";
+
+/**
+ * A time field made of spinbuttons: type the digits or use the arrows, and
+ * the field moves on by itself. A quick list offers common times. The value
+ * is always "HH:MM" in 24-hour time, whatever the reader sees.
+ */
+export function TimePicker({
+  label,
+  hint,
+  error,
+  value,
+  defaultValue = null,
+  onValueChange,
+  hourCycle,
+  step = 1,
+  listStep = 30,
+  min,
+  max,
+  disabledTimes,
+  enabledTimes,
+  locale = "en",
+  disabled,
+  required,
+  id,
+  className,
+}: TimePickerProps) {
+  const autoId = React.useId();
+  const fieldId = id ?? autoId;
+  const [inner, setInner] = React.useState<string | null>(defaultValue);
+  const current = value !== undefined ? value : inner;
+  const total = toMinutes(current);
+  const cycle = hourCycle ?? (new Intl.DateTimeFormat(locale, { hour: "numeric" }).resolvedOptions().hourCycle?.startsWith("h1") ? 12 : 24);
+  const [open, setOpen] = React.useState(false);
+  const list = React.useRef<HTMLUListElement>(null);
+  const buffer = React.useRef("");
+  const segments = React.useRef(new Map<Segment, HTMLSpanElement>());
+  const order: Segment[] = cycle === 12 ? ["hour", "minute", "period"] : ["hour", "minute"];
+
+  const rules: TimeRules = { min, max, disabled: disabledTimes, enabled: enabledTimes };
+  const unavailable = total !== null && !isTimeAllowed(total, rules);
+
+  /** Arrow keys land on the next allowed time in their direction, never on a refused one. */
+  const move = (target: number, direction: 1 | -1, by: number) => {
+    const next = nextAllowed(wrap(target, 1440), direction, by, rules);
+    if (next !== null) commit(next);
+  };
+
+  const commit = (minutes: number | null) => {
+    // Typed and stepped times stay inside [min, max], like the quick list.
+    const bounded = minutes === null ? null : Math.min(toMinutes(max) ?? 1439, Math.max(toMinutes(min) ?? 0, wrap(minutes, 1440)));
+    const next = bounded === null ? null : fromMinutes(bounded);
+    if (value === undefined) setInner(next);
+    onValueChange?.(next);
+  };
+
+  const base = total ?? 9 * 60;
+  const hours = Math.floor(base / 60);
+  const minutes = base % 60;
+  const isPm = hours >= 12;
+
+  const focusNext = (segment: Segment, direction = 1) => {
+    const index = order.indexOf(segment) + direction;
+    if (order[index]) segments.current.get(order[index])?.focus();
+  };
+
+  const setHour = (hour: number) => commit(hour * 60 + minutes);
+  const setMinute = (minute: number) => commit(hours * 60 + minute);
+
+  const onKeyDown = (event: React.KeyboardEvent, segment: Segment) => {
+    const key = event.key;
+    if (key === "ArrowLeft" || key === "ArrowRight") {
+      event.preventDefault();
+      buffer.current = "";
+      focusNext(segment, key === "ArrowRight" ? 1 : -1);
+      return;
+    }
+    if (key === "ArrowUp" || key === "ArrowDown") {
+      event.preventDefault();
+      const direction = key === "ArrowUp" ? 1 : -1;
+      if (segment === "hour") move(wrap(hours + direction, 24) * 60 + minutes, direction, 60);
+      else if (segment === "minute") move(hours * 60 + wrap(Math.round(minutes / step) * step + direction * step, 60), direction, step);
+      else {
+        const flipped = nearestAllowed(wrap(base + (isPm ? -720 : 720), 1440), rules);
+        if (flipped !== null) commit(flipped);
+      }
+      return;
+    }
+    if (segment === "period" && /^[ap]$/i.test(key)) {
+      event.preventDefault();
+      const wantPm = key.toLowerCase() === "p";
+      if (wantPm !== isPm) commit(base + (wantPm ? 720 : -720));
+      // Typed times may land on a refused one; the field snaps when focus leaves it.
+      return;
+    }
+    if (key === "Backspace" || key === "Delete") {
+      event.preventDefault();
+      buffer.current = "";
+      commit(null);
+      return;
+    }
+    if (!/^\d$/.test(key) || segment === "period") return;
+    event.preventDefault();
+    buffer.current = (buffer.current + key).slice(-2);
+    const typed = Number(buffer.current);
+    if (segment === "hour") {
+      const limit = cycle === 12 ? 12 : 23;
+      const hour24 = cycle === 12 ? (typed % 12) + (isPm ? 12 : 0) : typed;
+      if (typed <= limit) setHour(hour24);
+      // One digit is enough when no second digit could follow it.
+      if (buffer.current.length === 2 || typed * 10 > limit) {
+        buffer.current = "";
+        focusNext(segment);
+      }
+    } else {
+      if (typed < 60) setMinute(typed);
+      if (buffer.current.length === 2 || typed * 10 >= 60) {
+        buffer.current = "";
+        focusNext(segment);
+      }
+    }
+  };
+
+  const displayHour = total === null ? "--" : cycle === 12 ? String(((hours + 11) % 12) + 1) : pad(hours);
+  const displayMinute = total === null ? "--" : pad(minutes);
+  const format = new Intl.DateTimeFormat(locale, { hour: "numeric", minute: "2-digit", hourCycle: cycle === 12 ? "h12" : "h23", timeZone: "UTC" });
+  const spoken = (value: number) => format.format(new Date(Date.UTC(2000, 0, 1, Math.floor(value / 60), value % 60)));
+
+  const low = toMinutes(min) ?? 0;
+  const high = toMinutes(max) ?? 1439;
+  // With enabledTimes the list offers exactly the allowed slots, exact times
+  // included; otherwise it walks the grid and shows refused times dimmed.
+  const grid: number[] = [];
+  for (let at = low; at <= high; at += listStep) grid.push(at);
+  const exact = (Array.isArray(enabledTimes) ? enabledTimes : enabledTimes === undefined ? [] : [enabledTimes])
+    .filter((matcher): matcher is string => typeof matcher === "string" && !matcher.includes("-"))
+    .map((time) => toMinutes(time))
+    .filter((minutes): minutes is number => minutes !== null);
+  const options = enabledTimes === undefined ? grid : [...new Set([...grid, ...exact])].sort((a, b) => a - b).filter((at) => isTimeAllowed(at, rules));
+  const shownAt = total !== null ? options.reduce((best, at) => (Math.abs(at - total) < Math.abs(best - total) ? at : best), options[0] ?? low) : (options.find((at) => isTimeAllowed(at, rules)) ?? low);
+
+  // Open the list centred on the current time, once the popover has laid out.
+  // Only the list scrolls, never the page.
+  React.useEffect(() => {
+    if (!open) return;
+    const frame = requestAnimationFrame(() => {
+      const scroller = list.current;
+      const anchor = scroller?.querySelector<HTMLElement>("[data-anchor]");
+      if (!scroller || !anchor) return;
+      const box = scroller.getBoundingClientRect();
+      const rect = anchor.getBoundingClientRect();
+      scroller.scrollTop += rect.top - box.top - (scroller.clientHeight - rect.height) / 2;
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [open]);
+
+  const segmentProps = (segment: Segment, now: number | null, lowest: number, highest: number, text: string) => ({
+    ref: (element: HTMLSpanElement | null) => {
+      if (element) segments.current.set(segment, element);
+      else segments.current.delete(segment);
+    },
+    role: "spinbutton",
+    tabIndex: disabled ? -1 : 0,
+    "aria-label": segment === "hour" ? "Hours" : segment === "minute" ? "Minutes" : "AM or PM",
+    "aria-valuemin": lowest,
+    "aria-valuemax": highest,
+    "aria-valuenow": now ?? undefined,
+    "aria-valuetext": total === null ? "Empty" : text,
+    "aria-disabled": disabled || undefined,
+    className: "ml-time-picker-segment",
+    "data-empty": total === null || undefined,
+    onKeyDown: (event: React.KeyboardEvent) => !disabled && onKeyDown(event, segment),
+    onFocus: () => (buffer.current = ""),
+  });
+
+  return (
+    <Field id={fieldId} label={label} hint={hint} error={error} required={required} disabled={disabled} className={cx("ml-time-picker", className)}>
+      <div
+        className="ml-input ml-time-picker-control"
+        role="group"
+        id={fieldId}
+        aria-label={typeof label === "string" ? label : "Time"}
+        aria-describedby={fieldDescription(fieldId, { hint, error })}
+        aria-invalid={error || unavailable ? true : undefined}
+        data-disabled={disabled || undefined}
+        data-unavailable={unavailable || undefined}
+        onBlur={(event) => {
+          // Snap a refused time to the nearest allowed one when the reader moves on.
+          if (event.currentTarget.contains(event.relatedTarget as Node) || !unavailable || total === null) return;
+          commit(nearestAllowed(total, rules));
+        }}
+      >
+        <span {...segmentProps("hour", total === null ? null : hours, 0, 23, displayHour)}>{displayHour}</span>
+        <span className="ml-time-picker-colon" aria-hidden="true">
+          :
+        </span>
+        <span {...segmentProps("minute", total === null ? null : minutes, 0, 59, displayMinute)}>{displayMinute}</span>
+        {cycle === 12 ? (
+          <span {...segmentProps("period", total === null ? null : isPm ? 1 : 0, 0, 1, isPm ? "PM" : "AM")} data-period="">
+            {total === null ? "--" : isPm ? "PM" : "AM"}
+          </span>
+        ) : null}
+        <Popover
+          label="Choose a time"
+          open={open}
+          onOpenChange={setOpen}
+          side="bottom"
+          align="end"
+          trigger={
+            <button type="button" className="ml-time-picker-open" aria-label="Choose from a list" disabled={disabled}>
+              <IconClock aria-hidden="true" size="1em" />
+            </button>
+          }
+        >
+          <ul ref={list} className="ml-time-picker-list" role="listbox" aria-label="Times">
+            {options.map((option) => (
+              <li key={option} role="presentation">
+                <button
+                  type="button"
+                  role="option"
+                  aria-selected={option === total}
+                  aria-disabled={!isTimeAllowed(option, rules) || undefined}
+                  disabled={!isTimeAllowed(option, rules)}
+                  className="ml-time-picker-option"
+                  data-anchor={option === shownAt || undefined}
+                  onClick={() => {
+                    commit(option);
+                    setOpen(false);
+                  }}
+                >
+                  {spoken(option)}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </Popover>
+      </div>
+    </Field>
+  );
+}

package/snapshot/source/packages/components/time-picker/times.ts

@@ -0,0 +1,76 @@
+/**
+ * Times of day as minutes since midnight, and the rules that allow or refuse
+ * them. Every range is half-open, [from, to): "12:00-13:00" covers 12:00 to
+ * 12:59, so a lunch break ends when 13:00 becomes free again, and opening
+ * hours "09:00-17:00" offer a last start at 16:59.
+ */
+export type TimeMatcher = string | { from: string; to: string } | ((time: string) => boolean);
+export type TimeMatchers = TimeMatcher | TimeMatcher[];
+
+const pad = (value: number) => String(value).padStart(2, "0");
+
+export const toMinutes = (value: string | null | undefined) => {
+  if (!value || !/^\d{2}:\d{2}$/.test(value)) return null;
+  const [hours, minutes] = value.split(":").map(Number);
+  return hours * 60 + minutes;
+};
+
+export const fromMinutes = (total: number) => `${pad(Math.floor(total / 60) % 24)}:${pad(total % 60)}`;
+
+function inRange(minutes: number, from: string, to: string) {
+  const start = toMinutes(from);
+  const end = toMinutes(to);
+  if (start === null || end === null) return false;
+  // A range that ends before it starts runs past midnight, like "22:00-06:00".
+  return start <= end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
+}
+
+export function matchesTime(minutes: number, matchers?: TimeMatchers): boolean {
+  if (matchers === undefined) return false;
+  const list = Array.isArray(matchers) ? matchers : [matchers];
+  const time = fromMinutes(minutes);
+  return list.some((matcher) => {
+    if (typeof matcher === "function") return matcher(time);
+    if (typeof matcher === "string") {
+      const [from, to] = matcher.split("-").map((part) => part.trim());
+      return to ? inRange(minutes, from, to) : toMinutes(from) === minutes;
+    }
+    return inRange(minutes, matcher.from, matcher.to);
+  });
+}
+
+export interface TimeRules {
+  min?: string;
+  max?: string;
+  disabled?: TimeMatchers;
+  /** When given, only these times can be picked (min, max and disabled still apply). */
+  enabled?: TimeMatchers;
+}
+
+export function isTimeAllowed(minutes: number, rules: TimeRules) {
+  const low = toMinutes(rules.min) ?? 0;
+  const high = toMinutes(rules.max) ?? 1439;
+  return minutes >= low && minutes <= high && !matchesTime(minutes, rules.disabled) && (rules.enabled === undefined || matchesTime(minutes, rules.enabled));
+}
+
+/** The first allowed time from `start` moving by `step` minutes in `direction`, wrapping at midnight. */
+export function nextAllowed(start: number, direction: 1 | -1, step: number, rules: TimeRules): number | null {
+  const size = Math.max(1, step);
+  for (let moved = 0; moved < 1440; moved += size) {
+    const minutes = (((start + direction * moved) % 1440) + 1440) % 1440;
+    if (isTimeAllowed(minutes, rules)) return minutes;
+  }
+  // Nothing on the step grid: fall back to minute by minute.
+  if (size > 1) return nextAllowed(start, direction, 1, rules);
+  return null;
+}
+
+/** The allowed time closest to `minutes`; on a tie, the later one. */
+export function nearestAllowed(minutes: number, rules: TimeRules): number | null {
+  if (isTimeAllowed(minutes, rules)) return minutes;
+  for (let distance = 1; distance < 1440; distance++) {
+    if (minutes + distance <= 1439 && isTimeAllowed(minutes + distance, rules)) return minutes + distance;
+    if (minutes - distance >= 0 && isTimeAllowed(minutes - distance, rules)) return minutes - distance;
+  }
+  return null;
+}

package/snapshot/source/packages/components/timeline/timeline.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import * as React from "react";
+import { IconCheck } from "@mlola-ui/icons";
+import { cx } from "../_internal/react";
+
+type TimelineStatus = "complete" | "current" | "upcoming";
+type TimelineTone = "neutral" | "primary" | "info" | "success" | "warning" | "danger";
+
+const Timeline = React.forwardRef<HTMLOListElement, React.OlHTMLAttributes<HTMLOListElement>>(
+  ({ className, children, ...rest }, ref) => (
+    <ol ref={ref} className={cx("ml-timeline", className)} {...rest}>
+      {children}
+    </ol>
+  )
+);
+Timeline.displayName = "Timeline";
+
+interface TimelineItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "title"> {
+  /** Progress through a sequence: done, happening now, or still to come. */
+  status?: TimelineStatus;
+  /** Colours an event marker, for activity feeds: a failed deploy, a merged change. */
+  tone?: TimelineTone;
+  time?: React.ReactNode;
+  /** A machine-readable time for `<time dateTime>`. */
+  dateTime?: string;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  /** Replaces the status mark inside the marker. */
+  icon?: React.ReactNode;
+}
+
+/**
+ * One event: a marker on the rail, then a title with its time and an
+ * optional description. Anything passed as children (a quote, a card, a
+ * diff) sits under the description, still aligned to the text column.
+ */
+const TimelineItem = React.forwardRef<HTMLLIElement, TimelineItemProps>(
+  ({ status = "upcoming", tone, time, dateTime, title, description, icon, className, children, ...rest }, ref) => (
+    <li ref={ref} className={cx("ml-timeline-item", className)} data-status={status} aria-current={status === "current" ? "step" : undefined} {...rest}>
+      <TimelineDot status={status} data-tone={tone}>
+        {icon}
+      </TimelineDot>
+      <div className="ml-timeline-body">
+        <div className="ml-timeline-heading">
+          <TimelineTitle>{title}</TimelineTitle>
+          {time != null ? <TimelineTime dateTime={dateTime}>{time}</TimelineTime> : null}
+        </div>
+        {description != null ? <TimelineDescription>{description}</TimelineDescription> : null}
+        {children != null ? <div className="ml-timeline-content">{children}</div> : null}
+      </div>
+    </li>
+  )
+);
+TimelineItem.displayName = "TimelineItem";
+
+interface TimelineDotProps extends React.HTMLAttributes<HTMLSpanElement> {
+  status?: TimelineStatus;
+}
+
+const TimelineDot = React.forwardRef<HTMLSpanElement, TimelineDotProps>(
+  ({ status = "upcoming", className, children, ...rest }, ref) => (
+    <span
+      ref={ref}
+      aria-hidden="true"
+      data-status={status}
+      className={cx("ml-timeline-marker", className)}
+      {...rest}
+    >
+      {children ?? getStatusFallback(status)}
+    </span>
+  )
+);
+TimelineDot.displayName = "TimelineDot";
+
+function getStatusFallback(status: TimelineStatus) {
+  if (status === "complete") return <IconCheck size="0.75rem" />;
+  if (status === "current") return <span className="ml-timeline-pulse" />;
+  return null;
+}
+
+const TimelineTime = React.forwardRef<HTMLTimeElement, React.TimeHTMLAttributes<HTMLTimeElement>>(
+  ({ className, children, ...rest }, ref) => (
+    <time ref={ref} className={cx("ml-timeline-time", className)} {...rest}>
+      {children}
+    </time>
+  )
+);
+TimelineTime.displayName = "TimelineTime";
+
+const TimelineTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, children, ...rest }, ref) => (
+    <p ref={ref} className={cx("ml-timeline-title", className)} {...rest}>
+      {children}
+    </p>
+  )
+);
+TimelineTitle.displayName = "TimelineTitle";
+
+const TimelineDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, children, ...rest }, ref) => (
+    <p ref={ref} className={cx("ml-timeline-description", className)} {...rest}>
+      {children}
+    </p>
+  )
+);
+TimelineDescription.displayName = "TimelineDescription";
+export {
+  Timeline,
+  TimelineItem,
+  TimelineDot,
+  TimelineTime,
+  TimelineTitle,
+  TimelineDescription };
+export type { TimelineStatus, TimelineTone, TimelineItemProps, TimelineDotProps };