premium-ds 0.1.0

package/src/components/date-picker/date-utils.ts

@@ -0,0 +1,55 @@
+/* date-picker shared pure helpers - 'YYYY-MM-DD' civil-date math, month/weekday constants, tz-offset label. */
+
+export const MONTHS: string[] = [
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December',
+];
+export const DOW: string[] = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'];
+
+export const pad = (n: number): string => String(n).padStart(2, '0');
+export const key = (d: Date): string =>
+  d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate());
+export function parse(k: string): Date {
+  const p = k.split('-').map(Number);
+  return new Date(p[0], p[1] - 1, p[2]);
+}
+export const today = (): string => key(new Date());
+export const add = (k: string, days: number): string => {
+  const d = parse(k);
+  d.setDate(d.getDate() + days);
+  return key(d);
+};
+export const col = (d: Date): number => (d.getDay() + 6) % 7; // Monday-first column 0-6
+
+/* 42 cells, Monday-first, covering the month of (y, m) */
+export function grid(y: number, m: number): Date[] {
+  const lead = (new Date(y, m, 1).getDay() + 6) % 7;
+  const days: Date[] = [];
+  for (let i = 0; i < 42; i++) days.push(new Date(y, m, 1 - lead + i));
+  return days;
+}
+
+/* 'Europe/Riga' - 'Europe/Riga - GMT+3'; dateKey gives the DST-correct offset for that date, else now. */
+export function tzLabel(tz: string, dateKey?: string): string {
+  try {
+    const at = dateKey ? parse(dateKey) : new Date();
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      timeZoneName: 'shortOffset',
+    }).formatToParts(at);
+    const name = parts.find((p) => p.type === 'timeZoneName');
+    return tz.replace(/_/g, ' ') + (name ? ' - ' + name.value : '');
+  } catch (_e) {
+    return tz;
+  }
+}

package/src/components/date-picker/field-shell.tsx

@@ -0,0 +1,78 @@
+'use client';
+
+/* FieldShell + useControllable - the variant-blind .fld chrome and a controlled/uncontrolled state hook. */
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { Icon, type IconName } from '../icon/Icon';
+
+const { useState, useCallback } = React;
+
+export function useControllable<T>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (next: T) => void,
+): [T, (next: T) => void] {
+  const controlled = value !== undefined;
+  const [inner, setInner] = useState<T>(defaultValue);
+  const val = controlled ? (value as T) : inner;
+  const commit = useCallback(
+    (next: T) => {
+      if (!controlled) setInner(next);
+      if (onChange) onChange(next);
+    },
+    [controlled, onChange],
+  );
+  return [val, commit];
+}
+
+export interface FieldShellProps {
+  variant: string;
+  label?: string;
+  required?: boolean;
+  invalid?: boolean;
+  message?: ReactNode;
+  icon: IconName;
+  className?: string;
+  children?: ReactNode;
+}
+
+export function FieldShell({
+  variant,
+  label,
+  required,
+  invalid,
+  message,
+  icon,
+  className,
+  children,
+}: FieldShellProps) {
+  const cls = ['fld', variant, 'fld--has-lead', invalid ? 'is-error' : '', className || '']
+    .filter(Boolean)
+    .join(' ');
+  return (
+    <div className={cls}>
+      {label ? (
+        <span className="fld__label">
+          {label}
+          {required ? (
+            <span className="fld__req" aria-hidden="true">
+              *
+            </span>
+          ) : null}
+        </span>
+      ) : null}
+      <div className="fld__control">
+        {children}
+        <span className="fld__icon fld__icon--lead" aria-hidden="true">
+          <Icon name={icon} size="md" />
+        </span>
+      </div>
+      {message ? (
+        <div className="fld__msg">
+          <span>{message}</span>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/date-picker/glide-pill.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+/* GlidePill + useGlide - one persistent pill that springs between hovered cells, never a per-cell remount. */
+
+import * as React from 'react';
+import type { RefObject } from 'react';
+import { motion } from 'motion/react';
+import { UIMotion } from '../../tokens/motion-tokens';
+
+const SM = UIMotion;
+const { useRef, useState, useEffect, useCallback } = React;
+
+export interface GlideRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface GlideApi {
+  rect: GlideRect | null;
+  active: boolean;
+  enter: (el: HTMLElement | null) => void;
+  leave: () => void;
+}
+
+export function useGlide<T extends HTMLElement = HTMLElement>(
+  containerRef: RefObject<T | null>,
+): GlideApi {
+  const [rect, setRect] = useState<GlideRect | null>(null);
+  const [active, setActive] = useState(false);
+  const enter = useCallback(
+    (el: HTMLElement | null) => {
+      const c = containerRef.current;
+      if (!c || !el) return;
+      const cb = c.getBoundingClientRect();
+      const tb = el.getBoundingClientRect();
+      setRect({ x: tb.left - cb.left, y: tb.top - cb.top, width: tb.width, height: tb.height });
+      setActive(true);
+    },
+    [containerRef],
+  );
+  const leave = useCallback(() => setActive(false), []);
+  return { rect, active, enter, leave };
+}
+
+export interface GlidePillProps {
+  className?: string;
+  rect: GlideRect | null;
+  active: boolean;
+}
+
+export function GlidePill({ className, rect, active }: GlidePillProps) {
+  /* `wasActive` trails one render: the first appearance lands in place, later moves travel on the spring. */
+  const wasActive = useRef(false);
+  useEffect(() => {
+    wasActive.current = active;
+  });
+  const travel = wasActive.current && active ? SM.t.settle : { duration: 0 };
+  return (
+    <motion.span
+      className={className}
+      aria-hidden="true"
+      initial={false}
+      animate={{
+        x: rect ? rect.x : 0,
+        y: rect ? rect.y : 0,
+        width: rect ? rect.width : 0,
+        height: rect ? rect.height : 0,
+        opacity: active && rect ? 1 : 0,
+      }}
+      transition={{
+        x: travel,
+        y: travel,
+        width: travel,
+        height: travel,
+        opacity: { duration: SM.dur.fast, ease: active ? SM.ease.standard : SM.ease.exit },
+      }}
+    ></motion.span>
+  );
+}

package/src/components/date-picker/time-core.tsx

@@ -0,0 +1,305 @@
+'use client';
+
+/* TimeSegments - the segmented HH:MM machine: every keystroke interpreted (never inserted); commit is live and clamped (saturate, never error). */
+
+import * as React from 'react';
+
+const { useState, useRef, useEffect } = React;
+
+type Meridiem = 'AM' | 'PM';
+type Segment = 'h' | 'm';
+interface Pending {
+  seg: Segment;
+  d: number;
+}
+
+export interface TimeSegmentsProps {
+  value?: string | null;
+  onCommit?: (value: string) => void;
+  format?: '24h' | '12h';
+  minuteStep?: number;
+  min?: string | null;
+  max?: string | null;
+  disabled?: boolean;
+  ariaLabel?: string;
+  className?: string;
+}
+
+const tsgPad = (n: number): string => String(n).padStart(2, '0');
+const tsgDisp12 = (h24: number): number => ((h24 + 11) % 12) + 1;
+const tsgToH24 = (d12: number, mer: Meridiem): number => (d12 % 12) + (mer === 'PM' ? 12 : 0);
+
+/* feed one digit into a bounded two-digit segment; done = saturated (can't take another). */
+function tsgFeed(pend: number | null, d: number, hi: number): { val: number; done: boolean } {
+  if (pend != null) {
+    const n = pend * 10 + d;
+    if (n <= hi) return { val: n, done: true };
+  }
+  return { val: d, done: d * 10 > hi };
+}
+
+export function TimeSegments({
+  value = null,
+  onCommit,
+  format = '24h',
+  minuteStep = 5,
+  min = null,
+  max = null,
+  disabled = false,
+  ariaLabel = 'Time',
+  className = '',
+}: TimeSegmentsProps) {
+  const is12 = format === '12h';
+  const seed = value ? value.split(':').map(Number) : [null, null];
+
+  const [h, setHState] = useState<number | null>(seed[0]);
+  const [m, setMState] = useState<number | null>(seed[1]);
+  const [mer, setMer] = useState<Meridiem>(seed[0] != null && seed[0] >= 12 ? 'PM' : 'AM');
+  const [pend, setPendState] = useState<Pending | null>(null);
+
+  /* live mirrors - blur fires synchronously before re-render, so blur-commit reads refs, not stale closure state. */
+  const hLive = useRef<number | null>(seed[0]);
+  const mLive = useRef<number | null>(seed[1]);
+  const pendLive = useRef<Pending | null>(null);
+  const setH = (v: number | null) => {
+    hLive.current = v;
+    setHState(v);
+  };
+  const setM = (v: number | null) => {
+    mLive.current = v;
+    setMState(v);
+  };
+  const setPend = (v: Pending | null) => {
+    pendLive.current = v;
+    setPendState(v);
+  };
+
+  const hRef = useRef<HTMLSpanElement>(null);
+  const mRef = useRef<HTMLSpanElement>(null);
+  const merRef = useRef<HTMLSpanElement>(null);
+  const lastRef = useRef<string | null>(value || null);
+
+  /* external value changes re-seed; our own commits (matched via lastRef) are left alone, never clobbering in-flight typing. */
+  useEffect(() => {
+    if ((value || null) === lastRef.current) return;
+    lastRef.current = value || null;
+    const p = value ? value.split(':').map(Number) : [null, null];
+    setH(p[0]);
+    setM(p[1]);
+    if (p[0] != null) setMer(p[0] >= 12 ? 'PM' : 'AM');
+    setPend(null);
+  }, [value]);
+
+  function tryCommit(nh: number | null, nm: number | null) {
+    if (nh == null || nm == null) return;
+    let t = tsgPad(nh) + ':' + tsgPad(nm);
+    if (min && t < min) t = min;
+    if (max && t > max) t = max;
+    const p = t.split(':').map(Number);
+    if (p[0] !== nh) {
+      setH(p[0]);
+      setMer(p[0] >= 12 ? 'PM' : 'AM');
+      setPend(null);
+    }
+    if (p[1] !== nm) setM(p[1]);
+    if (t === lastRef.current) return;
+    lastRef.current = t;
+    if (onCommit) onCommit(t);
+  }
+
+  const focusSeg = (r: React.RefObject<HTMLSpanElement | null>) => {
+    if (r.current) r.current.focus();
+  };
+
+  function onHKey(e: React.KeyboardEvent<HTMLSpanElement>) {
+    const k = e.key;
+    if (/^[0-9]$/.test(k)) {
+      const pd = pend && pend.seg === 'h' ? pend.d : null;
+      const r = tsgFeed(pd, +k, is12 ? 12 : 23);
+      const nh = is12 ? tsgToH24(r.val === 0 ? 12 : r.val, mer) : r.val;
+      setH(nh);
+      if (!is12) setMer(nh >= 12 ? 'PM' : 'AM');
+      setPend(r.done ? null : { seg: 'h', d: r.val });
+      if (r.done) {
+        focusSeg(mRef);
+        tryCommit(nh, mLive.current);
+      }
+    } else if (k === 'ArrowUp' || k === 'ArrowDown') {
+      const dir = k === 'ArrowUp' ? 1 : -1;
+      const nh = h == null ? new Date().getHours() : (h + dir + 24) % 24;
+      setH(nh);
+      setMer(nh >= 12 ? 'PM' : 'AM');
+      setPend(null);
+      tryCommit(nh, mLive.current);
+    } else if (k === 'Backspace' || k === 'Delete') {
+      setH(null);
+      setPend(null);
+    } else if (k === 'ArrowRight' || k === ':' || k === ';') {
+      focusSeg(mRef);
+    } else if (k === 'Tab') {
+      return;
+    } else if (k.length === 1 && !e.metaKey && !e.ctrlKey) {
+      /* swallow */
+    } else return;
+    e.preventDefault();
+  }
+
+  function onMKey(e: React.KeyboardEvent<HTMLSpanElement>) {
+    const k = e.key;
+    if (/^[0-9]$/.test(k)) {
+      const pd = pend && pend.seg === 'm' ? pend.d : null;
+      const r = tsgFeed(pd, +k, 59);
+      setM(r.val);
+      setPend(r.done ? null : { seg: 'm', d: r.val });
+      if (r.done) {
+        if (is12) focusSeg(merRef);
+        tryCommit(hLive.current, r.val);
+      }
+    } else if (k === 'ArrowUp' || k === 'ArrowDown') {
+      const dir = k === 'ArrowUp' ? 1 : -1;
+      let nm;
+      if (m == null) {
+        nm = (Math.round(new Date().getMinutes() / minuteStep) * minuteStep) % 60;
+      } else {
+        /* step to the NEXT grid point, so 07 + ↑(step 5) lands on 10 */
+        const next =
+          dir > 0
+            ? (Math.floor(m / minuteStep) + 1) * minuteStep
+            : (Math.ceil(m / minuteStep) - 1) * minuteStep;
+        nm = ((next % 60) + 60) % 60;
+      }
+      setM(nm);
+      setPend(null);
+      tryCommit(hLive.current, nm);
+    } else if (k === 'Backspace' || k === 'Delete') {
+      if (m == null && !(pend && pend.seg === 'm')) {
+        focusSeg(hRef);
+      } else {
+        setM(null);
+        setPend(null);
+      }
+    } else if (k === 'ArrowLeft') {
+      focusSeg(hRef);
+    } else if (k === 'ArrowRight' && is12) {
+      focusSeg(merRef);
+    } else if (k === 'Tab') {
+      return;
+    } else if (k.length === 1 && !e.metaKey && !e.ctrlKey) {
+      /* swallow */
+    } else return;
+    e.preventDefault();
+  }
+
+  function setMeridiem(next: Meridiem) {
+    setMer(next);
+    if (h != null) {
+      const nh = tsgToH24(tsgDisp12(h), next);
+      setH(nh);
+      tryCommit(nh, mLive.current);
+    }
+  }
+  function onMerKey(e: React.KeyboardEvent<HTMLSpanElement>) {
+    const k = e.key;
+    if (k === 'a' || k === 'A') setMeridiem('AM');
+    else if (k === 'p' || k === 'P') setMeridiem('PM');
+    else if (k === 'ArrowUp' || k === 'ArrowDown') setMeridiem(mer === 'AM' ? 'PM' : 'AM');
+    else if (k === 'ArrowLeft') focusSeg(mRef);
+    else if (k === 'Tab') {
+      return;
+    } else if (k.length === 1 && !e.metaKey && !e.ctrlKey) {
+      /* swallow */
+    } else return;
+    e.preventDefault();
+  }
+
+  function onPaste(e: React.ClipboardEvent<HTMLDivElement>) {
+    if (disabled) return;
+    const txt = (e.clipboardData.getData('text') || '').trim();
+    const mt =
+      txt.match(/^(\d{1,2})[:h.\s]?(\d{2})?\s*([ap])\.?m?\.?$/i) ||
+      txt.match(/^(\d{1,2})[:h.\s]?(\d{2})?$/);
+    if (!mt) return;
+    e.preventDefault();
+    let hh = +mt[1];
+    const mm = mt[2] != null ? +mt[2] : 0;
+    if (mt[3]) hh = tsgToH24(hh, /^p/i.test(mt[3]) ? 'PM' : 'AM');
+    if (hh > 23 || mm > 59) return;
+    setH(hh);
+    setM(mm);
+    setMer(hh >= 12 ? 'PM' : 'AM');
+    setPend(null);
+    tryCommit(hh, mm);
+  }
+
+  const onSegBlur = (seg: Segment) => () => {
+    if (pendLive.current && pendLive.current.seg === seg) {
+      setPend(null);
+      tryCommit(hLive.current, mLive.current);
+    }
+  };
+
+  /* pending digit overrides canonical display, so typing '0' in 12h shows '00', not a premature '12'. */
+  const hText =
+    pend && pend.seg === 'h' ? tsgPad(pend.d) : h == null ? '--' : tsgPad(is12 ? tsgDisp12(h) : h);
+  const mText = pend && pend.seg === 'm' ? tsgPad(pend.d) : m == null ? '--' : tsgPad(m);
+
+  const segCls = (empty: boolean): string => 'tsg__seg' + (empty ? ' is-empty' : '');
+  const tab = disabled ? -1 : 0;
+
+  return (
+    <div
+      className={('tsg' + (disabled ? ' is-disabled' : '') + ' ' + className).trim()}
+      role="group"
+      aria-label={ariaLabel}
+      aria-disabled={disabled || undefined}
+      onPaste={onPaste}
+    >
+      <span
+        ref={hRef}
+        className={segCls(h == null && !(pend && pend.seg === 'h'))}
+        role="spinbutton"
+        tabIndex={tab}
+        aria-label="Hours"
+        aria-valuemin={is12 ? 1 : 0}
+        aria-valuemax={is12 ? 12 : 23}
+        aria-valuenow={h == null ? undefined : is12 ? tsgDisp12(h) : h}
+        aria-valuetext={h == null ? 'Empty' : hText}
+        onKeyDown={disabled ? undefined : onHKey}
+        onBlur={onSegBlur('h')}
+      >
+        {hText}
+      </span>
+      <span className="tsg__sep" aria-hidden="true">
+        :
+      </span>
+      <span
+        ref={mRef}
+        className={segCls(m == null && !(pend && pend.seg === 'm'))}
+        role="spinbutton"
+        tabIndex={tab}
+        aria-label="Minutes"
+        aria-valuemin={0}
+        aria-valuemax={59}
+        aria-valuenow={m == null ? undefined : m}
+        aria-valuetext={m == null ? 'Empty' : mText}
+        onKeyDown={disabled ? undefined : onMKey}
+        onBlur={onSegBlur('m')}
+      >
+        {mText}
+      </span>
+      {is12 ? (
+        <span
+          ref={merRef}
+          className="tsg__seg tsg__seg--mer"
+          role="spinbutton"
+          tabIndex={tab}
+          aria-label="AM or PM"
+          aria-valuetext={mer}
+          onKeyDown={disabled ? undefined : onMerKey}
+        >
+          {mer}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/src/components/dialog/Dialog.tsx

@@ -0,0 +1,181 @@
+'use client';
+
+/* Dialog - styled modal surface; a thin consumer of <Overlay mode="dialog">. */
+import * as React from 'react';
+import { Overlay } from '../overlay/Overlay';
+import { Icon } from '../icon/Icon';
+import { IconSlot } from '../icon/IconSlot';
+
+const { useRef: dlgUseRef, useEffect: dlgUseEffect, useId: dlgUseId } = React;
+
+export interface DialogProps {
+  /** Controlled open state. Omit for uncontrolled (use defaultOpen + trigger). */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Optional element cloned to open the dialog on click (uncontrolled ergonomics). */
+  trigger?: React.ReactElement | null;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+  /** 'danger' tints the header icon badge + is the convention for destructive confirms. */
+  tone?: 'default' | 'danger';
+  /** Your own icon node for the header badge (alert dialogs). */
+  icon?: React.ReactNode;
+  /** Close button + backdrop/Esc dismissal. Default true. */
+  dismissible?: boolean;
+  /** Action row - a node, or a render fn `(close) => node` so uncontrolled dialogs can dismiss. */
+  footer?: React.ReactNode | ((close: () => void) => React.ReactNode);
+  children?: React.ReactNode;
+  id?: string;
+}
+
+/* Flag the body's scroll edges (data-scroll-top/-bottom) so dialog.css :has() can earn the header lift + footer divider. */
+function useScrollEdges(ref: React.RefObject<HTMLElement>) {
+  dlgUseEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const update = () => {
+      el.toggleAttribute('data-scroll-top', el.scrollTop > 1);
+      el.toggleAttribute(
+        'data-scroll-bottom',
+        el.scrollTop + el.clientHeight < el.scrollHeight - 1,
+      );
+    };
+    update();
+    el.addEventListener('scroll', update, { passive: true });
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => {
+      el.removeEventListener('scroll', update);
+      ro.disconnect();
+    };
+  }, [ref]);
+}
+
+interface DialogSurfaceProps {
+  baseId: string;
+  size: 'sm' | 'md' | 'lg';
+  tone: 'default' | 'danger';
+  icon: React.ReactNode;
+  title: React.ReactNode;
+  description: React.ReactNode;
+  dismissible: boolean;
+  footerContent: React.ReactNode;
+  onRequestClose: () => void;
+  children?: React.ReactNode;
+}
+
+function DialogSurface({
+  baseId,
+  size,
+  tone,
+  icon,
+  title,
+  description,
+  dismissible,
+  footerContent,
+  onRequestClose,
+  children,
+}: DialogSurfaceProps) {
+  const bodyRef = dlgUseRef<HTMLDivElement>(null);
+  const titleId = baseId + '-title';
+  const descId = baseId + '-desc';
+
+  useScrollEdges(bodyRef);
+
+  return (
+    <section
+      className="dialog"
+      role="dialog"
+      aria-modal="true"
+      data-size={size === 'md' ? undefined : size}
+      data-tone={tone === 'default' ? undefined : tone}
+      aria-labelledby={title ? titleId : undefined}
+      aria-describedby={description ? descId : undefined}
+    >
+      <header className="dialog__header">
+        {icon && (
+          <span className="dialog__icon">
+            <IconSlot size="md">{icon}</IconSlot>
+          </span>
+        )}
+        <div className="dialog__heading">
+          {title && (
+            <h2 className="dialog__title" id={titleId}>
+              {title}
+            </h2>
+          )}
+          {description && (
+            <p className="dialog__desc" id={descId}>
+              {description}
+            </p>
+          )}
+        </div>
+        {dismissible && (
+          <button
+            type="button"
+            className="dialog__close"
+            aria-label="Close dialog"
+            onClick={onRequestClose}
+          >
+            <Icon name="x" size="sm" weight="bold" />
+          </button>
+        )}
+      </header>
+
+      <div className="dialog__body" ref={bodyRef}>
+        {children}
+      </div>
+
+      {footerContent && <footer className="dialog__footer">{footerContent}</footer>}
+    </section>
+  );
+}
+
+export function Dialog({
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  trigger = null,
+  title,
+  description = null,
+  size = 'md',
+  tone = 'default',
+  icon = null,
+  dismissible = true,
+  footer = null,
+  children,
+  id,
+}: DialogProps) {
+  const autoId = dlgUseId();
+  const baseId = id || 'dialog-' + autoId;
+
+  return (
+    <Overlay
+      mode="dialog"
+      id={baseId}
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      trigger={trigger}
+      dismissible={dismissible}
+    >
+      {({ close }) => (
+        <DialogSurface
+          baseId={baseId}
+          size={size}
+          tone={tone}
+          icon={icon}
+          title={title}
+          description={description}
+          dismissible={dismissible}
+          footerContent={typeof footer === 'function' ? footer(close) : footer}
+          onRequestClose={close}
+        >
+          {children}
+        </DialogSurface>
+      )}
+    </Overlay>
+  );
+}