@jcsoftdev/ui 0.1.7 → 0.2.0

package/src/utils/form-bubble.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { type MouseEvent, useEffect, useReducer, useRef, useState } from "react";
+
+/**
+ * Native form participation for custom toggles. The visible control is a
+ * button; a visually hidden input mirrors its state so FormData, `required`
+ * validation, `form` association and form-level change listeners keep working.
+ */
+export function useFormBubble(form?: string) {
+  const [control, setControl] = useState<HTMLElement | null>(null);
+  const [input, setInput] = useState<HTMLInputElement | null>(null);
+  const stoppedRef = useRef(false);
+  const [interactions, markInteraction] = useReducer((count: number) => count + 1, 0);
+  // Defaults to true before mount so the input also exists in server markup.
+  const isFormControl = control ? !!form || !!control.closest("form") : true;
+
+  function onControlClick(event: MouseEvent, interacted = true) {
+    if (interacted) markInteraction();
+    if (input && isFormControl) {
+      stoppedRef.current = event.isPropagationStopped();
+      // The hidden input re-dispatches the click, so stop the button's own copy.
+      if (!stoppedRef.current) event.stopPropagation();
+    }
+  }
+
+  return {
+    control,
+    setControl,
+    input,
+    setInput,
+    stoppedRef,
+    interactions,
+    isFormControl,
+    onControlClick,
+  };
+}
+
+export type FormBubble = ReturnType<typeof useFormBubble>;
+
+/** Runs `onReset` when the associated form resets. */
+export function useFormReset(
+  control: HTMLElement | null,
+  form: string | undefined,
+  onReset: () => void,
+) {
+  const resetRef = useRef(onReset);
+  useEffect(() => {
+    resetRef.current = onReset;
+  });
+  useEffect(() => {
+    if (!control) return;
+    const owner = form ? control.ownerDocument.getElementById(form) : control.closest("form");
+    if (!(owner instanceof HTMLFormElement)) return;
+    const reset = () => resetRef.current();
+    owner.addEventListener("reset", reset);
+    return () => owner.removeEventListener("reset", reset);
+  }, [control, form]);
+}
+
+function useControlSize(control: HTMLElement | null) {
+  const [size, setSize] = useState<{ width: number; height: number } | undefined>();
+  useEffect(() => {
+    if (!control) return setSize(undefined);
+    const update = () => setSize({ width: control.offsetWidth, height: control.offsetHeight });
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(control, { box: "border-box" });
+    return () => observer.disconnect();
+  }, [control]);
+  return size;
+}
+
+export interface BubbleInputProps {
+  type: "checkbox" | "radio";
+  checked: boolean | "indeterminate";
+  bubble: FormBubble;
+  name?: string | undefined;
+  value?: string | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  form?: string | undefined;
+}
+
+export function BubbleInput({
+  type,
+  checked,
+  bubble,
+  name,
+  value,
+  required,
+  disabled,
+  form,
+}: BubbleInputProps) {
+  const { control, input, setInput, stoppedRef, interactions } = bubble;
+  const size = useControlSize(control);
+  const stopClickRef = useRef(false);
+  const prevCheckedRef = useRef(checked);
+  const prevInteractionsRef = useRef(interactions);
+  const initialRef = useRef(checked === true);
+
+  useEffect(() => {
+    if (!input) return;
+    const isUserInteraction = interactions !== prevInteractionsRef.current;
+    prevInteractionsRef.current = interactions;
+    const changed = prevCheckedRef.current !== checked;
+    prevCheckedRef.current = checked;
+    if (!changed) return;
+    const setter = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype,
+      "checked",
+    )?.set;
+    if (!setter) return;
+    const bubbles = !(isUserInteraction && stoppedRef.current);
+    stopClickRef.current = !isUserInteraction;
+    input.indeterminate = checked === "indeterminate";
+    setter.call(input, checked === true);
+    input.dispatchEvent(new Event("click", { bubbles }));
+    stopClickRef.current = false;
+  }, [input, checked, interactions, stoppedRef]);
+
+  return (
+    <input
+      type={type}
+      aria-hidden
+      defaultChecked={initialRef.current}
+      required={required}
+      disabled={disabled}
+      name={name}
+      value={value}
+      form={form}
+      tabIndex={-1}
+      ref={setInput}
+      onClick={(event) => {
+        if (stopClickRef.current) event.stopPropagation();
+      }}
+      style={{
+        ...size,
+        position: "absolute",
+        pointerEvents: "none",
+        opacity: 0,
+        margin: 0,
+        transform: "translateX(-100%)",
+      }}
+    />
+  );
+}

package/src/utils/index.ts

@@ -1,2 +1,10 @@
-export { cn } from "./cn.js";
+export type { ClassNames } from "./class-names.js";
+export {
+  type ClassMergeConfig,
+  type ClassMergeTheme,
+  type Cn,
+  cn,
+  createCn,
+  extendCn,
+} from "./cn.js";
 export { usePrefersReducedMotion } from "./reduced-motion.js";

package/src/utils/roving-focus.ts

@@ -0,0 +1,116 @@
+import { type FocusEvent, type KeyboardEvent, useCallback, useRef, useState } from "react";
+import { composeHandlers } from "./compose.js";
+
+export type RovingOrientation = "horizontal" | "vertical";
+export type RovingDirection = "ltr" | "rtl";
+export type RovingIntent = "first" | "last" | "prev" | "next";
+
+export interface RovingFocusOptions {
+  /** Restricts arrows to one axis; both axes work when omitted. */
+  orientation?: RovingOrientation | undefined;
+  /** Flips ArrowLeft/ArrowRight in `rtl`. */
+  dir?: RovingDirection | undefined;
+  /** Wraps around at the ends. Defaults to `true`. */
+  loop?: boolean | undefined;
+  /** Item that owns the tab stop until focus moves (the selected one, if any). */
+  activeId?: string | null | undefined;
+}
+
+const ITEM_ATTR = "data-roving-item";
+
+export function getRovingIntent(
+  key: string,
+  { orientation, dir = "ltr" }: Pick<RovingFocusOptions, "orientation" | "dir">,
+): RovingIntent | undefined {
+  if (key === "Home" || key === "PageUp") return "first";
+  if (key === "End" || key === "PageDown") return "last";
+  const horizontal = key === "ArrowLeft" || key === "ArrowRight";
+  const vertical = key === "ArrowUp" || key === "ArrowDown";
+  if (!horizontal && !vertical) return undefined;
+  if (orientation === "vertical" && horizontal) return undefined;
+  if (orientation === "horizontal" && vertical) return undefined;
+  const forward =
+    key === "ArrowRight"
+      ? dir === "ltr"
+      : key === "ArrowLeft"
+        ? dir === "rtl"
+        : key === "ArrowDown";
+  return forward ? "next" : "prev";
+}
+
+export function findRovingTarget(
+  items: HTMLElement[],
+  current: HTMLElement,
+  intent: RovingIntent,
+  loop: boolean,
+): HTMLElement | undefined {
+  if (intent === "first") return items[0];
+  if (intent === "last") return items[items.length - 1];
+  const index = items.indexOf(current);
+  const step = intent === "next" ? 1 : -1;
+  const next = index + step;
+  if (next >= 0 && next < items.length) return items[next];
+  return loop ? items[(next + items.length) % items.length] : undefined;
+}
+
+export interface RovingItemOptions<E extends HTMLElement = HTMLElement> {
+  /** Disabled items leave the arrow order and the tab order. */
+  disabled?: boolean | undefined;
+  onKeyDown?: ((event: KeyboardEvent<E>) => void) | undefined;
+  onFocus?: ((event: FocusEvent<E>) => void) | undefined;
+  /** Called after focus moved to `target` through `key`. */
+  onNavigate?: ((target: HTMLElement, key: string) => void) | undefined;
+}
+
+/**
+ * Roving tabindex for composite widgets. Spread `rootProps` on the container
+ * and `getItemProps(id, ...)` on each item; order comes from the DOM, so it
+ * works for any children (radios, tabs, segmented controls, menu items).
+ */
+export function useRovingFocus(options: RovingFocusOptions = {}) {
+  const { orientation, dir, loop = true, activeId } = options;
+  const rootRef = useRef<HTMLElement | null>(null);
+  const [focusedId, setFocusedId] = useState<string | null>(null);
+  const stopId = focusedId ?? activeId ?? null;
+
+  const getItems = useCallback(
+    () => Array.from(rootRef.current?.querySelectorAll<HTMLElement>(`[${ITEM_ATTR}]`) ?? []),
+    [],
+  );
+
+  const setRoot = useCallback((node: HTMLElement | null) => {
+    rootRef.current = node;
+  }, []);
+
+  const rootProps = {
+    ref: setRoot,
+    tabIndex: stopId === null ? 0 : -1,
+    onFocus: (event: FocusEvent<HTMLElement>) => {
+      if (event.target === event.currentTarget) getItems()[0]?.focus();
+    },
+  };
+
+  function getItemProps<E extends HTMLElement = HTMLElement>(
+    id: string,
+    item: RovingItemOptions<E> = {},
+  ) {
+    const { disabled, onKeyDown, onFocus, onNavigate } = item;
+    return {
+      [ITEM_ATTR]: disabled ? undefined : "",
+      tabIndex: !disabled && stopId === id ? 0 : -1,
+      onFocus: composeHandlers(onFocus, () => setFocusedId(id)),
+      onKeyDown: composeHandlers(onKeyDown, (event: KeyboardEvent<E>) => {
+        if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+        const intent = getRovingIntent(event.key, { orientation, dir });
+        if (!intent) return;
+        event.preventDefault();
+        const target = findRovingTarget(getItems(), event.currentTarget, intent, loop);
+        if (!target) return;
+        target.focus();
+        onNavigate?.(target, event.key);
+      }),
+    };
+  }
+
+  return { rootProps, getItemProps };
+}

package/src/utils/slot.tsx

@@ -0,0 +1,91 @@
+import {
+  Children,
+  cloneElement,
+  Fragment,
+  type HTMLAttributes,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+  type RefCallback,
+} from "react";
+
+type AnyProps = Record<string, unknown>;
+
+export interface SlotProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+  ref?: Ref<HTMLElement>;
+}
+
+function setRef<T>(ref: Ref<T> | undefined, value: T | null): void {
+  if (typeof ref === "function") ref(value);
+  else if (ref) (ref as { current: T | null }).current = value;
+}
+
+export function composeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  return (node) => {
+    const cleanups: Array<() => void> = [];
+    for (const ref of refs) {
+      const result = typeof ref === "function" ? (ref as RefCallback<T>)(node) : undefined;
+      if (typeof ref !== "function") setRef(ref, node);
+      else if (typeof result === "function") cleanups.push(result as () => void);
+      else cleanups.push(() => setRef(ref, null));
+    }
+    return () => {
+      for (const cleanup of cleanups) cleanup();
+    };
+  };
+}
+
+function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
+  const merged: AnyProps = { ...childProps };
+  for (const name of Object.keys(childProps)) {
+    const slotValue = slotProps[name];
+    const childValue = childProps[name];
+    if (/^on[A-Z]/.test(name)) {
+      if (typeof slotValue === "function" && typeof childValue === "function") {
+        merged[name] = (...args: unknown[]) => {
+          const result = childValue(...args);
+          slotValue(...args);
+          return result;
+        };
+      } else if (slotValue) {
+        merged[name] = slotValue;
+      }
+    } else if (name === "style") {
+      merged[name] = { ...(slotValue as object), ...(childValue as object) };
+    } else if (name === "className") {
+      merged[name] = [slotValue, childValue].filter(Boolean).join(" ");
+    } else if (name === "aria-describedby") {
+      const ids = new Set<string>();
+      for (const value of [childValue, slotValue]) {
+        if (typeof value !== "string") continue;
+        for (const id of value.trim().split(/\s+/)) if (id) ids.add(id);
+      }
+      merged[name] = ids.size > 0 ? [...ids].join(" ") : undefined;
+    }
+  }
+  return { ...slotProps, ...merged };
+}
+
+/**
+ * Renders its single child element with the Slot's own props merged in: handlers run
+ * child first, then slot; `className` is concatenated; `style` merges with the child
+ * winning; `aria-describedby` ids are unioned; refs are composed.
+ */
+export function Slot({ children, ref, ...slotProps }: SlotProps) {
+  if (Children.count(children) !== 1 || !isValidElement(children)) {
+    if (children || children === 0) {
+      throw new Error(
+        "Slot failed to slot onto its children. Expected a single React element child.",
+      );
+    }
+    return children ?? null;
+  }
+  const child = children as ReactElement<AnyProps & { ref?: Ref<HTMLElement> }>;
+  const merged = mergeProps(slotProps, child.props);
+  if (child.type !== Fragment) {
+    merged.ref = ref ? composeRefs(ref, child.props.ref) : child.props.ref;
+  }
+  return cloneElement(child, merged);
+}

package/src/utils/use-controllable-state.ts

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface ControllableStateOptions<T> {
+  /** Controlled value. `undefined` means uncontrolled. */
+  prop: T | undefined;
+  defaultProp: T;
+  onChange?: ((value: T) => void) | undefined;
+}
+
+type Updater<T> = T | ((prev: T) => T);
+
+/**
+ * Controlled/uncontrolled state. `onChange` fires only when the value really
+ * changes, for both modes; a controlled owner stays the source of truth.
+ */
+export function useControllableState<T>({
+  prop,
+  defaultProp,
+  onChange,
+}: ControllableStateOptions<T>): [T, (next: Updater<T>) => void] {
+  const [uncontrolled, setUncontrolled] = useState<T>(defaultProp);
+  const isControlled = prop !== undefined;
+  const value = isControlled ? prop : uncontrolled;
+
+  const valueRef = useRef(value);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    valueRef.current = value;
+    onChangeRef.current = onChange;
+  });
+
+  const setValue = useCallback(
+    (next: Updater<T>) => {
+      const resolved =
+        typeof next === "function" ? (next as (prev: T) => T)(valueRef.current) : next;
+      if (Object.is(resolved, valueRef.current)) return;
+      if (!isControlled) {
+        valueRef.current = resolved;
+        setUncontrolled(resolved);
+      }
+      onChangeRef.current?.(resolved);
+    },
+    [isControlled],
+  );
+
+  return [value, setValue];
+}

package/styles/Theme.kt

@@ -75,7 +75,7 @@ object UiColors {
         segOn = Color(0xFFFFFFFF),
         ink = Color(0xFF000000),
         ink2 = Color(0xFF4B4B57),
-        ink3 = Color(0xFF6D6D7A),
+        ink3 = Color(0xFF666673),
         accent = Color(0xFFFAA2A2),
         onAccent = Color(0xFF3F191A),
         accentInk = Color(0xFFA43A41),

package/styles/theme.css

@@ -183,6 +183,21 @@
   --text-m-meta: 13px;
   --text-m-meta--line-height: 1.4;
   --text-m-meta--font-weight: 400;
+  /* Size-only scale (px x 10, no line-height or weight) for dense UI text that must not inherit a role's weight. */
+  --text-fs-95: 9.5px;
+  --text-fs-100: 10px;
+  --text-fs-105: 10.5px;
+  --text-fs-110: 11px;
+  --text-fs-115: 11.5px;
+  --text-fs-120: 12px;
+  --text-fs-125: 12.5px;
+  --text-fs-130: 13px;
+  --text-fs-140: 14px;
+  --text-fs-150: 15px;
+  --text-fs-160: 16px;
+  --text-fs-220: 22px;
+  --text-fs-300: 30px;
+  --text-fs-440: 44px;
   --radius-button: var(--radius-button);
   --radius-input: var(--radius-input);
   --radius-badge: var(--radius-badge);

package/styles/tokens.css

@@ -15,7 +15,7 @@
   --seg-on: #ffffff;
   --ink: #000000;
   --ink-2: #4b4b57;
-  --ink-3: #6d6d7a;
+  --ink-3: #666673;
   --accent: #faa2a2;
   --on-accent: #3f191a;
   --accent-ink: #a43a41;

package/tokens/default.json

@@ -128,10 +128,10 @@
    {
     "name": "ink-3",
     "value": {
-     "light": "#6d6d7a",
+     "light": "#666673",
      "dark": "#8c8c98"
     },
-    "usage": "Metadatos y encabezados de tabla, sobre bg y surface (4.6:1 sobre bg en claro). Sobre surface-2 usa ink-2."
+    "usage": "Metadatos y encabezados de tabla, sobre bg, surface, surface-2 y sunken (4.5:1 o más en claro y oscuro)."
    },
    {
     "name": "accent",
@@ -738,6 +738,22 @@
   "families": {
    "sans": "\"Figtree\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif"
   },
+  "sizeScale": [
+   { "name": "fs-95", "fontSize": "9.5px" },
+   { "name": "fs-100", "fontSize": "10px" },
+   { "name": "fs-105", "fontSize": "10.5px" },
+   { "name": "fs-110", "fontSize": "11px" },
+   { "name": "fs-115", "fontSize": "11.5px" },
+   { "name": "fs-120", "fontSize": "12px" },
+   { "name": "fs-125", "fontSize": "12.5px" },
+   { "name": "fs-130", "fontSize": "13px" },
+   { "name": "fs-140", "fontSize": "14px" },
+   { "name": "fs-150", "fontSize": "15px" },
+   { "name": "fs-160", "fontSize": "16px" },
+   { "name": "fs-220", "fontSize": "22px" },
+   { "name": "fs-300", "fontSize": "30px" },
+   { "name": "fs-440", "fontSize": "44px" }
+  ],
   "groups": [
    {
     "name": "Títulos",