@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/containers/settings-layout/settings-layout.tsx

@@ -0,0 +1,85 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../../utils/cn.js";
+
+export type SettingsLayoutProps = ComponentPropsWithoutRef<"div">;
+
+/**
+ * Two-column settings grid (side nav + content). Collapses to one column at
+ * 940px or less of the ancestor `@container/page`.
+ */
+export function SettingsLayout({ className, ...props }: SettingsLayoutProps) {
+  return (
+    <div
+      className={cn(
+        "grid grid-cols-[220px_minmax(0,1fr)] items-start gap-6 @max-[940px]/page:grid-cols-1",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export type SettingsLayoutNavProps = ComponentPropsWithoutRef<"nav">;
+
+/** Sticky side nav that becomes a scrollable horizontal row on narrow pages. */
+export function SettingsLayoutNav({
+  "aria-label": ariaLabel = "Sections",
+  className,
+  ...props
+}: SettingsLayoutNavProps) {
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className={cn(
+        "sticky top-20 flex flex-col gap-px @max-[940px]/page:static @max-[940px]/page:flex-row @max-[940px]/page:overflow-x-auto",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export interface SettingsLayoutNavItemProps extends ComponentPropsWithoutRef<"button"> {
+  /** Currently visible section. */
+  active?: boolean;
+}
+
+export function SettingsLayoutNavItem({
+  active,
+  className,
+  type = "button",
+  ...props
+}: SettingsLayoutNavItemProps) {
+  return (
+    <button
+      type={type}
+      aria-current={active ? "true" : undefined}
+      className={cn(
+        "flex shrink-0 items-center gap-2.5 rounded-control px-2.5 py-[7px] font-medium text-[13px] text-ink-2 hover:bg-surface-2 hover:text-ink",
+        active && "bg-accent-soft font-semibold text-accent-ink",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export type SettingsLayoutMainProps = ComponentPropsWithoutRef<"div">;
+
+/**
+ * Content column: a single stack that becomes a 2-column masonry at 1180px of
+ * page width, where each direct child (a card) is not split across columns.
+ */
+export function SettingsLayoutMain({ className, ...props }: SettingsLayoutMainProps) {
+  return (
+    <div
+      className={cn(
+        "flex min-w-0 flex-col gap-4",
+        "@min-[1180px]/page:block @min-[1180px]/page:[columns:2_460px] @min-[1180px]/page:[column-gap:16px]",
+        "@min-[1180px]/page:[&>*]:mb-4 @min-[1180px]/page:[&>*]:[break-inside:avoid]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/containers/settings-row/index.ts

@@ -0,0 +1 @@
+export * from "./settings-row.js";

package/src/containers/settings-row/settings-row.tsx

@@ -0,0 +1,38 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../../utils/cn.js";
+
+export interface SettingsRowProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  title: ReactNode;
+  description?: ReactNode;
+  /** Control on the right: a switch, a button, etc. */
+  control?: ReactNode;
+  /** Id for the title element, so the control can reference it with `aria-labelledby`. */
+  titleId?: string;
+}
+
+export function SettingsRow({
+  title,
+  description,
+  control,
+  titleId,
+  className,
+  ...props
+}: SettingsRowProps) {
+  return (
+    <div
+      className={cn(
+        "flex flex-wrap items-center justify-between gap-x-4 gap-y-2.5 border-t-divider px-4 py-[13px] first:border-t-0",
+        className,
+      )}
+      {...props}
+    >
+      <div className="min-w-0 flex-[1_1_14rem] break-words">
+        <p id={titleId} className="font-semibold text-[13px]">
+          {title}
+        </p>
+        {description ? <p className="max-w-[60ch] text-[12px] text-ink-3">{description}</p> : null}
+      </div>
+      {control ? <div className="flex max-w-full shrink-0 items-center">{control}</div> : null}
+    </div>
+  );
+}

package/src/containers/table/index.ts

@@ -0,0 +1 @@
+export * from "./table.js";

package/src/containers/table/pin.ts

@@ -0,0 +1,91 @@
+export type PinSide = "left" | "right";
+
+/** Column ids pinned to each edge. Each list is ordered as the columns appear, left to right. */
+export interface PinnedColumns {
+  left?: readonly string[];
+  right?: readonly string[];
+}
+
+export interface PinPosition {
+  side: PinSide;
+  /** Distance in px from the pinned edge (the `left` or `right` sticky offset). */
+  offset: number;
+  /** Innermost pinned column of its side: the one that casts the edge shadow. */
+  edge: boolean;
+}
+
+/**
+ * Cumulative sticky offsets from measured column widths. Left columns stack from the left
+ * edge in order; right columns stack from the right edge, so the last id sits at offset 0.
+ * Ids without a measured width are ignored; an id listed on both sides keeps its left pin.
+ */
+export function computePinOffsets(
+  widths: Readonly<Record<string, number>>,
+  pinned: PinnedColumns,
+): Record<string, PinPosition> {
+  const result: Record<string, PinPosition> = {};
+  const left = (pinned.left ?? []).filter((id) => widths[id] !== undefined);
+  const right = (pinned.right ?? []).filter((id) => widths[id] !== undefined && !left.includes(id));
+
+  let offset = 0;
+  left.forEach((id, index) => {
+    result[id] = { side: "left", offset, edge: index === left.length - 1 };
+    offset += widths[id] ?? 0;
+  });
+
+  offset = 0;
+  for (let index = right.length - 1; index >= 0; index -= 1) {
+    const id = right[index] as string;
+    result[id] = { side: "right", offset, edge: index === 0 };
+    offset += widths[id] ?? 0;
+  }
+  return result;
+}
+
+/** Drops ids that no longer exist, duplicates, and ids pinned on both sides. */
+export function sanitizePinned(
+  pinned: PinnedColumns,
+  knownIds: readonly string[] | null,
+): { left: string[]; right: string[] } {
+  const keep = (id: unknown): id is string =>
+    typeof id === "string" && (knownIds === null || knownIds.includes(id));
+  const left = [...new Set((pinned.left ?? []).filter(keep))];
+  const right = [...new Set((pinned.right ?? []).filter(keep))].filter((id) => !left.includes(id));
+  return { left, right };
+}
+
+/** Pins `id` to `side`, or unpins it when `side` is null; lists follow `order` (column order). */
+export function setColumnPin(
+  pinned: PinnedColumns,
+  id: string,
+  side: PinSide | null,
+  order: readonly string[],
+): { left: string[]; right: string[] } {
+  const without = (list: readonly string[] | undefined) => (list ?? []).filter((x) => x !== id);
+  const left = without(pinned.left);
+  const right = without(pinned.right);
+  if (side === "left") left.push(id);
+  if (side === "right") right.push(id);
+  const rank = (x: string) => {
+    const index = order.indexOf(x);
+    return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+  };
+  return {
+    left: left.sort((a, b) => rank(a) - rank(b)),
+    right: right.sort((a, b) => rank(a) - rank(b)),
+  };
+}
+
+export function parseStoredPins(raw: string | null): { left: string[]; right: string[] } | null {
+  if (!raw) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (typeof value !== "object" || value === null) return null;
+    const { left, right } = value as { left?: unknown; right?: unknown };
+    const list = (x: unknown) =>
+      Array.isArray(x) ? x.filter((item): item is string => typeof item === "string") : [];
+    return { left: list(left), right: list(right) };
+  } catch {
+    return null;
+  }
+}

package/src/containers/table/table.tsx

@@ -0,0 +1,406 @@
+"use client";
+
+import { ArrowLeftToLine, ArrowRightToLine, PinOff } from "lucide-react";
+import {
+  type ComponentPropsWithoutRef,
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { cn } from "../../utils/cn.js";
+import {
+  computePinOffsets,
+  type PinnedColumns,
+  type PinPosition,
+  type PinSide,
+  parseStoredPins,
+  sanitizePinned,
+  setColumnPin,
+} from "./pin.js";
+
+export type { PinnedColumns, PinSide } from "./pin.js";
+
+export interface TableLabels {
+  pinLeft: string;
+  pinRight: string;
+  unpin: string;
+}
+
+const DEFAULT_LABELS: TableLabels = {
+  pinLeft: "Fijar a la izquierda",
+  pinRight: "Fijar a la derecha",
+  unpin: "Desfijar",
+};
+
+interface PinContextValue {
+  positions: Record<string, PinPosition>;
+  scrolledStart: boolean;
+  scrolledEnd: boolean;
+  labels: TableLabels;
+  pin: (columnId: string, side: PinSide | null) => void;
+}
+
+const PinContext = createContext<PinContextValue | null>(null);
+
+export interface TableProps extends ComponentPropsWithoutRef<"table"> {
+  /** Controlled pinned columns (ids of `columnId`). Pair it with `onPinnedColumnsChange`. */
+  pinnedColumns?: PinnedColumns;
+  /** Initial pins when uncontrolled. */
+  defaultPinnedColumns?: PinnedColumns;
+  onPinnedColumnsChange?: (pinned: { left: string[]; right: string[] }) => void;
+  /** localStorage key that remembers the user's pins (uncontrolled only). */
+  pinStorageKey?: string;
+  /** Texts of the pin buttons (Spanish by default). */
+  labels?: Partial<TableLabels>;
+  /** Classes of the scroll wrapper. */
+  wrapperClassName?: string;
+}
+
+function readStorage(key: string): string | null {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string): void {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // Storage can be blocked (private mode, quota); pins just stop persisting.
+  }
+}
+
+function sameLists(a: PinnedColumns, b: PinnedColumns): boolean {
+  return (
+    JSON.stringify([a.left ?? [], a.right ?? []]) === JSON.stringify([b.left ?? [], b.right ?? []])
+  );
+}
+
+/**
+ * Table inside its own horizontal scroll wrapper. Give columns a `columnId` (header and cells)
+ * and mark header cells `pinnable` to let the user pin them to the left or right edge: pinned
+ * columns stay sticky while the rest scrolls.
+ */
+export function Table({
+  className,
+  wrapperClassName,
+  pinnedColumns,
+  defaultPinnedColumns,
+  onPinnedColumnsChange,
+  pinStorageKey,
+  labels,
+  ...props
+}: TableProps) {
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const tableRef = useRef<HTMLTableElement>(null);
+  const controlled = pinnedColumns !== undefined;
+  const [internal, setInternal] = useState<PinnedColumns>(defaultPinnedColumns ?? {});
+  const [knownIds, setKnownIds] = useState<string[] | null>(null);
+  const [positions, setPositions] = useState<Record<string, PinPosition>>({});
+  const [scrolled, setScrolled] = useState({ start: false, end: false });
+
+  useEffect(() => {
+    if (!pinStorageKey || controlled) return;
+    const stored = parseStoredPins(readStorage(pinStorageKey));
+    if (stored) setInternal(stored);
+  }, [pinStorageKey, controlled]);
+
+  const pinned = sanitizePinned((controlled ? pinnedColumns : internal) ?? {}, knownIds);
+  const pinnedKey = JSON.stringify(pinned);
+
+  const measure = useCallback(() => {
+    const table = tableRef.current;
+    const wrapper = wrapperRef.current;
+    if (!table || !wrapper) return;
+    const ids: string[] = [];
+    const widths: Record<string, number> = {};
+    for (const cell of table.querySelectorAll<HTMLElement>("thead [data-column-id]")) {
+      const id = cell.dataset.columnId;
+      if (!id) continue;
+      ids.push(id);
+      widths[id] = cell.getBoundingClientRect().width;
+    }
+    setKnownIds((previous) =>
+      previous && previous.length === ids.length && previous.every((id, i) => id === ids[i])
+        ? previous
+        : ids,
+    );
+    const next = computePinOffsets(widths, JSON.parse(pinnedKey));
+    setPositions((previous) =>
+      JSON.stringify(previous) === JSON.stringify(next) ? previous : next,
+    );
+    const start = wrapper.scrollLeft > 0;
+    const end = wrapper.scrollLeft + wrapper.clientWidth < wrapper.scrollWidth - 1;
+    setScrolled((previous) =>
+      previous.start === start && previous.end === end ? previous : { start, end },
+    );
+  }, [pinnedKey]);
+
+  useLayoutEffect(() => {
+    measure();
+    const table = tableRef.current;
+    const wrapper = wrapperRef.current;
+    if (!table || !wrapper) return;
+    let frame = 0;
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(measure);
+    };
+    const resize = new ResizeObserver(schedule);
+    resize.observe(wrapper);
+    resize.observe(table);
+    for (const cell of table.querySelectorAll("thead [data-column-id]")) resize.observe(cell);
+    const mutation = new MutationObserver(schedule);
+    mutation.observe(table, { childList: true, subtree: true });
+    return () => {
+      cancelAnimationFrame(frame);
+      resize.disconnect();
+      mutation.disconnect();
+    };
+  }, [measure]);
+
+  const pin = useCallback(
+    (columnId: string, side: PinSide | null) => {
+      const next = setColumnPin(pinned, columnId, side, knownIds ?? []);
+      if (sameLists(next, pinned)) return;
+      if (!controlled) {
+        setInternal(next);
+        if (pinStorageKey) writeStorage(pinStorageKey, JSON.stringify(next));
+      }
+      onPinnedColumnsChange?.(next);
+    },
+    [pinned, knownIds, controlled, pinStorageKey, onPinnedColumnsChange],
+  );
+
+  const context: PinContextValue = {
+    positions,
+    scrolledStart: scrolled.start,
+    scrolledEnd: scrolled.end,
+    labels: { ...DEFAULT_LABELS, ...labels },
+    pin,
+  };
+
+  return (
+    <PinContext.Provider value={context}>
+      <div
+        ref={wrapperRef}
+        onScroll={measure}
+        className={cn("@container/table max-w-full overflow-x-auto", wrapperClassName)}
+      >
+        <table
+          ref={tableRef}
+          className={cn("w-full border-collapse text-[13px]", className)}
+          {...props}
+        />
+      </div>
+    </PinContext.Provider>
+  );
+}
+
+export function TableHead(props: ComponentPropsWithoutRef<"thead">) {
+  return <thead {...props} />;
+}
+
+export function TableBody(props: ComponentPropsWithoutRef<"tbody">) {
+  return <tbody {...props} />;
+}
+
+interface ColumnProps {
+  /** Identifies the column so it can be pinned. Use the same id on the header and its cells. */
+  columnId?: string;
+}
+
+interface AlignProps extends ColumnProps {
+  alignRight?: boolean;
+}
+
+/** Sticky styles and data attributes of a cell in a pinned column (empty otherwise). */
+function usePinnedCell(columnId: string | undefined, header: boolean) {
+  const context = useContext(PinContext);
+  const position = columnId ? context?.positions[columnId] : undefined;
+  if (!context || !columnId) return { context, attrs: {}, className: "", style: undefined };
+  const attrs = { "data-column-id": columnId, "data-pinned": position?.side };
+  if (!position) return { context, attrs, className: "", style: undefined };
+  const shadowed =
+    position.edge && (position.side === "left" ? context.scrolledStart : context.scrolledEnd);
+  const className = cn(
+    "sticky bg-surface",
+    header
+      ? "z-2"
+      : "z-1 group-hover/row:bg-surface-2 group-aria-selected/row:bg-accent-soft group-data-[selected=true]/row:bg-accent-soft",
+    shadowed && (position.side === "left" ? "shadow-pinned-start" : "shadow-pinned-end"),
+  );
+  const style: CSSProperties = { [position.side]: position.offset };
+  return { context, attrs, className, style };
+}
+
+function PinButtons({ columnId }: { columnId: string }) {
+  const context = useContext(PinContext);
+  if (!context) return null;
+  const side = context.positions[columnId]?.side;
+  const button =
+    "grid size-5 shrink-0 place-items-center rounded-xs text-ink-3 hover:bg-surface-2 hover:text-ink focus-visible:text-ink";
+  if (side) {
+    return (
+      <button
+        type="button"
+        aria-pressed="true"
+        aria-label={context.labels.unpin}
+        title={context.labels.unpin}
+        onClick={() => context.pin(columnId, null)}
+        className={cn(button, "text-accent-ink")}
+      >
+        <PinOff aria-hidden="true" className="size-3.5" />
+      </button>
+    );
+  }
+  return (
+    <span className="inline-flex shrink-0 items-center">
+      <button
+        type="button"
+        aria-pressed="false"
+        aria-label={context.labels.pinLeft}
+        title={context.labels.pinLeft}
+        onClick={() => context.pin(columnId, "left")}
+        className={button}
+      >
+        <ArrowLeftToLine aria-hidden="true" className="size-3.5" />
+      </button>
+      <button
+        type="button"
+        aria-pressed="false"
+        aria-label={context.labels.pinRight}
+        title={context.labels.pinRight}
+        onClick={() => context.pin(columnId, "right")}
+        className={button}
+      >
+        <ArrowRightToLine aria-hidden="true" className="size-3.5" />
+      </button>
+    </span>
+  );
+}
+
+export function TableHeaderCell({
+  className,
+  alignRight,
+  columnId,
+  pinnable,
+  children,
+  style,
+  ...props
+}: ComponentPropsWithoutRef<"th"> & AlignProps & { pinnable?: boolean }): ReactNode {
+  const pinned = usePinnedCell(columnId, true);
+  const showPin = pinnable && columnId && pinned.context;
+  return (
+    <th
+      className={cn(
+        "whitespace-nowrap border-b-divider px-4 py-2.5 text-left font-[650] text-[11px] text-ink-3 uppercase tracking-[.07em] @max-sm/table:px-2.5",
+        alignRight && "text-right",
+        pinned.className,
+        className,
+      )}
+      style={{ ...pinned.style, ...style }}
+      {...pinned.attrs}
+      {...props}
+    >
+      {showPin ? (
+        <span className={cn("inline-flex items-center gap-1", alignRight && "flex-row-reverse")}>
+          {children}
+          <PinButtons columnId={columnId} />
+        </span>
+      ) : (
+        children
+      )}
+    </th>
+  );
+}
+
+export function TableRow({ className, ...props }: ComponentPropsWithoutRef<"tr">) {
+  return (
+    <tr
+      className={cn("group/row border-b-divider last:border-b-0 hover:bg-surface-2", className)}
+      {...props}
+    />
+  );
+}
+
+export function TableCell({
+  className,
+  alignRight,
+  columnId,
+  style,
+  ...props
+}: ComponentPropsWithoutRef<"td"> & AlignProps) {
+  const pinned = usePinnedCell(columnId, false);
+  return (
+    <td
+      className={cn(
+        "px-4 py-[11px] align-middle @max-sm/table:px-2.5",
+        alignRight && "text-right",
+        pinned.className,
+        className,
+      )}
+      style={{ ...pinned.style, ...style }}
+      {...pinned.attrs}
+      {...props}
+    />
+  );
+}
+
+export interface TableLinkRowProps extends Omit<ComponentPropsWithoutRef<"tr">, "children"> {
+  /** Row destination: rendered as a real `<a href>` in the first cell. */
+  href: string;
+  /** Content of the first cell, wrapped by the anchor. */
+  primary: ReactNode;
+  /** `columnId` of the first cell, so that column can be pinned. */
+  primaryColumnId?: string;
+  /** Additional `<td>` cells of the row. */
+  children?: ReactNode;
+}
+
+/**
+ * Fully navigable table row: the real link lives in the first cell and, via a
+ * stretched link (positioned `<tr>` + anchor `::before` at `inset-0`), its
+ * click area covers the whole row without duplicating the link per cell.
+ */
+export function TableLinkRow({
+  href,
+  primary,
+  primaryColumnId,
+  children,
+  className,
+  ...props
+}: TableLinkRowProps) {
+  const pinned = usePinnedCell(primaryColumnId, false);
+  return (
+    <tr
+      className={cn(
+        "group/row relative border-b-divider last:border-b-0 hover:bg-surface-2",
+        className,
+      )}
+      {...props}
+    >
+      <td
+        className={cn("p-0 align-middle", pinned.className)}
+        style={pinned.style}
+        {...pinned.attrs}
+      >
+        <a
+          href={href}
+          className="block px-4 py-[11px] font-[650] text-ink no-underline before:absolute before:inset-0 before:content-[''] @max-sm/table:px-2.5"
+        >
+          {primary}
+        </a>
+      </td>
+      {children}
+    </tr>
+  );
+}

package/src/containers/timeline/index.ts

@@ -0,0 +1,6 @@
+export {
+  Timeline,
+  type TimelineFeedItem,
+  type TimelineFeedTone,
+  type TimelineProps,
+} from "./timeline.js";