premium-ds 0.1.0

package/src/components/overlay/sheet-drag.tsx

@@ -0,0 +1,146 @@
+'use client';
+
+/* sheet-drag - drag-to-dismiss for Overlay's sheet mode (dismiss - scrim - rubber-band - scroll handoff). */
+import * as React from 'react';
+import { useMotionValue, useTransform, useDragControls, animate, type PanInfo } from 'motion/react';
+import { UIMotion } from '../../tokens/motion-tokens';
+
+const sdSM = UIMotion;
+const { useEffect: sdUseEffect, useRef: sdUseRef } = React;
+
+const DISMISS_RATIO = 0.4;
+const DISMISS_VELOCITY = 500;
+const INTENT_PX = 4;
+const STRETCH_MAX = 0.06;
+
+/* nearest scrollable ancestor of `node`, stopping at the slot */
+function findScrollable(node: EventTarget | null, stop: HTMLElement | null): HTMLElement | null {
+  let el = node instanceof Element ? node : null;
+  while (el && el !== stop) {
+    const s = getComputedStyle(el);
+    if (
+      /(auto|scroll)/.test(s.overflowY + s.overflowX) &&
+      (el.scrollHeight > el.clientHeight || el.scrollWidth > el.clientWidth)
+    )
+      return el as HTMLElement;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+function useSheetDrag({
+  side,
+  slotRef,
+  enabled,
+  requestClose,
+}: {
+  side: 'right' | 'bottom';
+  slotRef: React.RefObject<HTMLElement>;
+  enabled: boolean;
+  requestClose: () => void;
+}) {
+  const axis = side === 'bottom' ? 'y' : 'x';
+  /* matches the `closed` variant so the scrim starts transparent */
+  const travel = useMotionValue<string | number>('100%');
+  const stretch = useMotionValue(1);
+  const controls = useDragControls();
+  const savedUserSelect = sdUseRef<string | null>(null);
+
+  /* suspend selection only while dragging; restore also covers unmount mid-drag */
+  function suspendSelection() {
+    const sel = window.getSelection();
+    if (sel) sel.removeAllRanges();
+    savedUserSelect.current = document.body.style.userSelect;
+    document.body.style.userSelect = 'none';
+  }
+  function restoreSelection() {
+    if (savedUserSelect.current === null) return;
+    document.body.style.userSelect = savedUserSelect.current;
+    savedUserSelect.current = null;
+  }
+  sdUseEffect(() => restoreSelection, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const progress = useTransform(travel, (v) => {
+    if (typeof v === 'string') return Math.min(Math.max(parseFloat(v) / 100 || 0, 0), 1);
+    const el = slotRef.current;
+    const size = el ? (axis === 'y' ? el.offsetHeight : el.offsetWidth) : Infinity;
+    return Math.min(Math.max(v / size, 0), 1);
+  });
+  const scrimOpacity = useTransform(progress, (p) => 1 - p);
+
+  /* pointer intent: watch the first few px, then hand off to drag or to scroll/selection */
+  function onPointerDown(e: React.PointerEvent) {
+    if (e.button !== 0) return;
+    const startX = e.clientX,
+      startY = e.clientY;
+    const scrollable = findScrollable(e.target, slotRef.current);
+    const onMove = (ev: PointerEvent) => {
+      const dx = ev.clientX - startX,
+        dy = ev.clientY - startY;
+      if (Math.max(Math.abs(dx), Math.abs(dy)) < INTENT_PX) return;
+      cleanup();
+      const along = axis === 'y' ? dy : dx;
+      const cross = axis === 'y' ? dx : dy;
+      if (Math.abs(along) <= Math.abs(cross)) return;
+      if (scrollable) {
+        if (along < 0) return;
+        if (axis === 'y' ? scrollable.scrollTop > 0 : scrollable.scrollLeft > 0) return;
+      }
+      suspendSelection();
+      /* framer may not fire onDragEnd (release exactly at threshold), so restore here too - idempotent with the onDragEnd restore */
+      window.addEventListener('pointerup', restoreSelection, { once: true });
+      window.addEventListener('pointercancel', restoreSelection, { once: true });
+      controls.start(ev);
+    };
+    const cleanup = () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', cleanup);
+      window.removeEventListener('pointercancel', cleanup);
+    };
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', cleanup);
+    window.addEventListener('pointercancel', cleanup);
+  }
+
+  /* overdrag away from the edge - damped, capped stretch (info.offset is raw; travel is clamped) */
+  function onDrag(_ev: PointerEvent | MouseEvent | TouchEvent, info: PanInfo) {
+    const el = slotRef.current;
+    if (!el) return;
+    const size = axis === 'y' ? el.offsetHeight : el.offsetWidth;
+    const o = info.offset[axis];
+    stretch.set(o < 0 ? 1 + Math.min(-o / size, 1) * STRETCH_MAX : 1);
+  }
+
+  function onDragEnd(_ev: PointerEvent | MouseEvent | TouchEvent, info: PanInfo) {
+    restoreSelection();
+    animate(stretch, 1, sdSM.t.settle);
+    const el = slotRef.current;
+    if (!el) return;
+    const size = axis === 'y' ? el.offsetHeight : el.offsetWidth;
+    if (info.offset[axis] > size * DISMISS_RATIO || info.velocity[axis] > DISMISS_VELOCITY)
+      requestClose();
+  }
+
+  const stretchStyle =
+    axis === 'y' ? { scaleY: stretch, originY: 1 } : { scaleX: stretch, originX: 1 };
+
+  const slotProps = enabled
+    ? {
+        drag: axis,
+        dragControls: controls,
+        dragListener: false,
+        dragMomentum: false,
+        dragConstraints: { top: 0, bottom: 0, left: 0, right: 0 },
+        /* away from the edge: hard clamp (stretch covers it); toward: free */
+        dragElastic: axis === 'y' ? { top: 0, bottom: 1 } : { left: 0, right: 1 },
+        onPointerDown,
+        onDrag,
+        onDragEnd,
+        style: { [axis]: travel, ...stretchStyle },
+      }
+    : { style: { [axis]: travel } }; // scrim coupling still applies
+
+  return { slotProps, scrimOpacity };
+}
+
+export { useSheetDrag };

package/src/components/pagination/Pagination.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+/* Pagination - pure cursor strip: mono range readout + prev/next, no page numbers. */
+
+import * as React from 'react';
+import { animate } from 'motion/react';
+import { UIMotion } from '../../tokens/motion-tokens';
+import { Icon } from '../icon/Icon';
+
+export interface PaginationProps {
+  /** Accessible name for the nav landmark - name the list ("Posts"), not "pagination". @default 'Pagination' */
+  label?: string;
+  /** Items currently shown, 1-based inclusive: `[from, to]` (e.g. `[26, 50]`). */
+  range: [number, number];
+  /** Total item count - render `of N` only when the API reports one; omit for endless lists. */
+  total?: number | null;
+  /** A previous cursor exists. @default false */
+  hasPrev?: boolean;
+  /** A next cursor exists. @default false */
+  hasNext?: boolean;
+  /** Fired when the previous arrow is pressed. */
+  onPrev?: () => void;
+  /** Fired when the next arrow is pressed. */
+  onNext?: () => void;
+  /** A page fetch is in flight: both arrows go inert, the clicked arrow carries the spinner. @default false */
+  loading?: boolean;
+  className?: string;
+}
+
+const { useEffect, useRef } = React;
+
+/* --space-2 in real px - tokens resolve to "0.5rem"; bare parseFloat gives 0.5, so convert rem-px */
+let pgnTravelPx: number | null = null;
+function pgnTravel() {
+  if (pgnTravelPx == null) {
+    const cs = getComputedStyle(document.documentElement);
+    const v = cs.getPropertyValue('--space-2').trim();
+    const n = parseFloat(v);
+    pgnTravelPx = v.endsWith('rem') ? n * parseFloat(cs.fontSize) : n;
+  }
+  return pgnTravelPx;
+}
+
+/* thin-space thousands grouping ("48 210") - section E mono-numeral convention */
+function pgnFormat(n: number) {
+  return n.toLocaleString('en-US').replace(/,/g, '\u2009');
+}
+
+export function Pagination({
+  label = 'Pagination',
+  range,
+  total = null,
+  hasPrev = false,
+  hasNext = false,
+  onPrev,
+  onNext,
+  loading = false,
+  className = '',
+}: PaginationProps) {
+  const rangeRef = useRef<HTMLSpanElement>(null);
+  const prevBtnRef = useRef<HTMLButtonElement>(null);
+  const nextBtnRef = useRef<HTMLButtonElement>(null);
+  const shownRef = useRef<[number, number]>(range); // last range rendered (skip first mount)
+  const lastDirRef = useRef(0); // -1 prev - +1 next - last arrow fired
+
+  const from = range[0];
+  const to = range[1];
+
+  /* direction-aware entrance: new numbers arrive from the side you traveled toward (one persistent node, imperative keyframes) */
+  useEffect(() => {
+    const pf = shownRef.current[0],
+      pt = shownRef.current[1];
+    if (pf === from && pt === to) return;
+    const dir = from > pf ? 1 : -1;
+    shownRef.current = range;
+    animate(rangeRef.current, { x: [dir * pgnTravel(), 0], opacity: [0, 1] }, UIMotion.t.enter);
+  }, [from, to]);
+
+  /* edge disables the focused arrow and focus falls to <body> - hand it to the surviving direction; activeElement guard avoids stealing focus */
+  useEffect(() => {
+    if (loading || document.activeElement !== document.body) return;
+    const d = lastDirRef.current;
+    if (d === 1 && !hasNext && hasPrev && prevBtnRef.current) prevBtnRef.current.focus();
+    if (d === -1 && !hasPrev && hasNext && nextBtnRef.current) nextBtnRef.current.focus();
+  }, [loading, hasPrev, hasNext]);
+
+  const prevBusy = loading && lastDirRef.current === -1;
+  const nextBusy = loading && lastDirRef.current === 1;
+
+  return (
+    <nav
+      className={('pgn ' + className).trim()}
+      aria-label={label}
+      aria-busy={loading || undefined}
+    >
+      <span className="pgn__readout" aria-live="polite">
+        <span className="pgn__range" ref={rangeRef}>
+          <b>
+            {pgnFormat(from)}-{pgnFormat(to)}
+          </b>
+          {total != null ? <span className="pgn__total"> of {pgnFormat(total)}</span> : null}
+        </span>
+      </span>
+      <div className="pgn__nav">
+        <button
+          type="button"
+          ref={prevBtnRef}
+          className={
+            'btn btn--ghost btn--sm pgn__btn pgn__btn--prev' + (prevBusy ? ' is-loading' : '')
+          }
+          disabled={!hasPrev || loading}
+          aria-label="Previous page"
+          onClick={() => {
+            lastDirRef.current = -1;
+            if (onPrev) onPrev();
+          }}
+        >
+          <Icon name="caret-left" size="sm" />
+          {prevBusy ? <span className="btn__spinner" aria-hidden="true"></span> : null}
+        </button>
+        <button
+          type="button"
+          ref={nextBtnRef}
+          className={
+            'btn btn--ghost btn--sm pgn__btn pgn__btn--next' + (nextBusy ? ' is-loading' : '')
+          }
+          disabled={!hasNext || loading}
+          aria-label="Next page"
+          onClick={() => {
+            lastDirRef.current = 1;
+            if (onNext) onNext();
+          }}
+        >
+          <Icon name="caret-right" size="sm" />
+          {nextBusy ? <span className="btn__spinner" aria-hidden="true"></span> : null}
+        </button>
+      </div>
+    </nav>
+  );
+}

package/src/components/pagination/pagination.css

@@ -0,0 +1,48 @@
+/* Pagination - cursor strip: layout, mono readout, square arrows + directional caret nudge (on Button vocabulary). */
+
+.pgn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+/* mono tabular readout; .pgn__range is the node Motion slides - keep it transformable (inline-block) */
+.pgn__readout {
+  font: var(--type-mono);
+  font-variant-numeric: tabular-nums;
+  color: var(--text-subtle);
+  white-space: nowrap;
+}
+.pgn__range {
+  display: inline-block;
+}
+.pgn__range b {
+  font-weight: var(--weight-medium);
+  color: var(--text-body);
+}
+
+/* arrows kept adjacent (not flanking the readout) so repeated paging needs no mouse travel and a growing readout never shifts them */
+.pgn__nav {
+  display: flex;
+  gap: var(--space-1);
+}
+.pgn__btn {
+  width: var(--control-height-sm);
+  padding: 0;
+}
+
+/* Caret nudges toward its direction on hover - a 1px optical cue. */
+.pgn__btn .icon {
+  transition: transform var(--duration-fast) var(--ease-standard);
+}
+.pgn__btn--prev:hover:not(:disabled) .icon {
+  transform: translateX(calc(var(--space-px) * -1));
+}
+.pgn__btn--next:hover:not(:disabled) .icon {
+  transform: translateX(var(--space-px));
+}
+
+/* loading: clicked arrow shows Button's spinner - hide its caret like button.css hides .btn__icon */
+.pgn__btn.is-loading .icon {
+  opacity: 0;
+}

package/src/components/radio-group/RadioGroup.tsx

@@ -0,0 +1,182 @@
+'use client';
+
+// RadioGroup - single-select rows or cards; one marker glides between dots via Motion layoutId.
+
+import * as React from 'react';
+import { motion, LayoutGroup } from 'motion/react';
+import { Icon } from '../icon/Icon';
+import { IconSlot } from '../icon/IconSlot';
+import { UIMotion } from '../../tokens/motion-tokens';
+
+const SM = UIMotion;
+
+export interface RadioOption {
+  /** The stored value - what `onChange` returns and `value` matches. */
+  value: string;
+  /** Visible label (sentence case). */
+  label: React.ReactNode;
+  /** Optional secondary line (muted) explaining the choice. */
+  description?: React.ReactNode;
+  /** Leading icon - your own node. CARDS only; ignored for rows. */
+  icon?: React.ReactNode;
+  /** Disable just this option. */
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps extends Omit<
+  React.FieldsetHTMLAttributes<HTMLFieldSetElement>,
+  'onChange'
+> {
+  /** Shared radio name - ties the options into one keyboard group. Required. */
+  name: string;
+  /** The selected value (controlled). */
+  value?: string;
+  /** Called with the chosen option's `value`. */
+  onChange?: (value: string) => void;
+  /** Group label / legend (sentence case). */
+  label?: React.ReactNode;
+  /** Persistent context shown under the legend, before the options. */
+  helper?: React.ReactNode;
+  /** Group-level error (e.g. required). Sets the error state + reveals the message. */
+  error?: React.ReactNode;
+  /** Show a danger `*` after the label. */
+  required?: boolean;
+  /** Show a muted "(optional)" after the label. */
+  optional?: boolean;
+  /** Skin: quiet rows (default) or selectable cards. */
+  variant?: 'rows' | 'cards';
+  /** Lay options out in a line instead of a stack. */
+  orientation?: 'vertical' | 'horizontal';
+  /** Control size: sm (dot 16) - md (default, dot 18). */
+  size?: 'sm' | 'md';
+  /** Disable the whole group. */
+  disabled?: boolean;
+  /** The options to choose between. */
+  options: RadioOption[];
+  className?: string;
+}
+
+function RadioGroup({
+  name,
+  value,
+  onChange,
+  label,
+  helper,
+  error,
+  required,
+  optional,
+  variant = 'rows',
+  orientation = 'vertical',
+  size = 'md',
+  disabled,
+  options = [],
+  className = '',
+  ...rest
+}: RadioGroupProps) {
+  const groupId = React.useId();
+
+  const cls = [
+    'rg',
+    variant === 'cards' ? 'rg--cards' : '',
+    orientation === 'horizontal' ? 'rg--horizontal' : '',
+    size === 'sm' ? 'rg--sm' : '',
+    error ? 'is-error' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <fieldset className={cls} aria-invalid={error ? true : undefined} {...rest}>
+      {label && (
+        <div className="rg__head">
+          <legend className="rg__label">
+            {label}
+            {required && (
+              <span className="rg__req" aria-hidden="true">
+                *
+              </span>
+            )}
+            {optional && <span className="rg__optional">(optional)</span>}
+          </legend>
+          {helper && <p className="rg__helper">{helper}</p>}
+        </div>
+      )}
+
+      <LayoutGroup id={groupId}>
+        <div className="rg__options">
+          {options.map((opt) => {
+            const selected = opt.value === value;
+            const isDisabled = disabled || opt.disabled;
+            return (
+              <label
+                key={opt.value}
+                className={[
+                  'rg-opt',
+                  selected ? 'is-selected' : '',
+                  isDisabled ? 'is-disabled' : '',
+                ]
+                  .filter(Boolean)
+                  .join(' ')}
+              >
+                <input
+                  className="rg-opt__input"
+                  type="radio"
+                  name={name}
+                  value={opt.value}
+                  checked={selected}
+                  disabled={isDisabled}
+                  onChange={() => onChange && onChange(opt.value)}
+                />
+                {variant === 'cards' && selected && (
+                  <motion.span
+                    className="rg__card-fill"
+                    layoutId="card-fill"
+                    transition={SM.t.layout}
+                    aria-hidden="true"
+                  ></motion.span>
+                )}
+                {variant === 'cards' && opt.icon && (
+                  <span className="rg-opt__icon">
+                    <IconSlot>{opt.icon}</IconSlot>
+                  </span>
+                )}
+                <span className="rg-opt__control">
+                  <span className="rg-opt__dot">
+                    {selected && (
+                      <motion.span
+                        className="rg__marker"
+                        layoutId="marker"
+                        transition={SM.t.layout}
+                        aria-hidden="true"
+                      ></motion.span>
+                    )}
+                  </span>
+                </span>
+                <span className="rg-opt__body">
+                  <span className="rg-opt__label">{opt.label}</span>
+                  {opt.description && <span className="rg-opt__desc">{opt.description}</span>}
+                </span>
+              </label>
+            );
+          })}
+        </div>
+      </LayoutGroup>
+
+      <div
+        className={'collapse collapse--fade rg__msg-wrap'}
+        data-open={error ? 'true' : 'false'}
+        data-axis="height"
+      >
+        <div className="collapse__inner">
+          <div className="rg__msg">
+            <Icon name="warning-circle" size="sm" weight="fill" />
+            {error}
+          </div>
+        </div>
+      </div>
+    </fieldset>
+  );
+}
+
+export { RadioGroup };