@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/brand/logo-mark.tsx

@@ -0,0 +1,40 @@
+import { createElement, type ReactNode } from "react";
+import { cn } from "../utils/cn.js";
+import { generateMark, type MarkNode, type MarkOptions } from "./generate.js";
+
+const camel = (name: string) => name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+
+function renderNode(node: MarkNode, key: number): ReactNode {
+  const props: Record<string, unknown> = { key };
+  for (const [name, value] of Object.entries(node.attrs)) {
+    if (value !== undefined) props[camel(name)] = value;
+  }
+  const children = [
+    ...(node.children ?? []).map(renderNode),
+    ...(node.text === undefined ? [] : [node.text]),
+  ];
+  return createElement(node.tag, props, ...children);
+}
+
+export interface LogoMarkProps extends MarkOptions {
+  /** CSS width of the mark; the height follows the aspect ratio. Defaults to the full container. */
+  size?: number | string;
+  className?: string;
+}
+
+/** Renders a generated brand mark as an inline `<svg role="img">`. */
+export function LogoMark({ size = "100%", className, ...options }: LogoMarkProps) {
+  const mark = generateMark(options);
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={mark.viewBox}
+      role="img"
+      aria-label={mark.label}
+      className={cn("block h-auto max-w-full", className)}
+      style={{ width: size }}
+    >
+      {mark.nodes.map(renderNode)}
+    </svg>
+  );
+}

package/src/brand/palettes.ts

@@ -0,0 +1,69 @@
+export interface BrandPalette {
+  id: string;
+  label: string;
+  /** Main fill of the shape. */
+  primary: string;
+  /** Second stop of gradients and decorations. */
+  secondary: string;
+  /** Wordmark color on a light background and glyph color over pale fills. */
+  ink: string;
+}
+
+/**
+ * The first seven mirror the library accent palettes (fill, second tone and deep ink);
+ * the rest are classic barbershop colorways. Marks keep their own colors, they never
+ * follow the surrounding `data-accent`.
+ */
+export const BRAND_PALETTES: readonly BrandPalette[] = [
+  { id: "coral", label: "Coral", primary: "#faa2a2", secondary: "#fec79e", ink: "#3f191a" },
+  { id: "durazno", label: "Durazno", primary: "#efae75", secondary: "#e1d695", ink: "#3b1f02" },
+  { id: "menta", label: "Menta", primary: "#77d3ad", secondary: "#8ee5ed", ink: "#002f1f" },
+  { id: "cielo", label: "Cielo", primary: "#76c9f8", secondary: "#c6d2ff", ink: "#002a3e" },
+  { id: "lavanda", label: "Lavanda", primary: "#bab3fe", secondary: "#f2c1f3", ink: "#252142" },
+  { id: "orquidea", label: "Orquídea", primary: "#eaa3d5", secondary: "#fec2c5", ink: "#391a31" },
+  { id: "grafito", label: "Grafito", primary: "#26262b", secondary: "#5a5a66", ink: "#1a1a1e" },
+  { id: "navaja", label: "Navaja", primary: "#1f2f57", secondary: "#c8372d", ink: "#14203d" },
+  { id: "bronce", label: "Bronce", primary: "#8a5a2b", secondary: "#d9a441", ink: "#2c1b0a" },
+  { id: "esmeralda", label: "Esmeralda", primary: "#14614a", secondary: "#9bd17f", ink: "#0a2e23" },
+  { id: "vino", label: "Vino", primary: "#6e1f3a", secondary: "#e08a6a", ink: "#2f0d19" },
+];
+
+export function findPalette(id: string): BrandPalette {
+  return BRAND_PALETTES.find((p) => p.id === id) ?? (BRAND_PALETTES[0] as BrandPalette);
+}
+
+const COLOR = /^(#[0-9a-f]{3,8}|(rgb|hsl)a?\([0-9a-z.,%\s/-]{1,48}\)|[a-z]{3,20})$/i;
+
+/** Accepts hex, rgb()/hsl() and plain color names only; anything else falls back. */
+export function safeColor(value: string | undefined, fallback: string): string {
+  const trimmed = (value ?? "").trim();
+  return COLOR.test(trimmed) ? trimmed : fallback;
+}
+
+function channels(color: string): [number, number, number] | null {
+  const hex = /^#([0-9a-f]{6}|[0-9a-f]{3})/i.exec(color)?.[1];
+  if (!hex) return null;
+  const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+  return [0, 2, 4].map((i) => Number.parseInt(full.slice(i, i + 2), 16)) as [
+    number,
+    number,
+    number,
+  ];
+}
+
+/** WCAG relative luminance of a hex color; other formats read as mid-dark. */
+export function luminance(color: string): number {
+  const rgb = channels(color);
+  if (!rgb) return 0.2;
+  const [r, g, b] = rgb.map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  }) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** The palette ink over pale fills, white over dark ones. */
+export function contentColor(fills: string[], ink: string): string {
+  const avg = fills.reduce((sum, c) => sum + luminance(c), 0) / fills.length;
+  return avg > 0.38 ? ink : "#ffffff";
+}

package/src/brand/rng.ts

@@ -0,0 +1,25 @@
+/** FNV-1a over UTF-16 code units; stable across runtimes. */
+export function hashString(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** Small deterministic PRNG (mulberry32): the same seed always yields the same sequence. */
+export function createRng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function pick<T>(rng: () => number, items: readonly T[]): T {
+  return items[Math.floor(rng() * items.length)] as T;
+}

package/src/calendar/day-chip/day-chip.tsx

@@ -0,0 +1,34 @@
+import { cn } from "../../utils/cn.js";
+import type { CalendarMarker } from "../internal/types.js";
+
+const TONE: Record<NonNullable<CalendarMarker["tone"]>, string> = {
+  danger: "bg-danger text-on-accent",
+  accent: "bg-accent-soft text-accent-ink shadow-inset-accent",
+};
+
+export interface DayChipProps {
+  marker: CalendarMarker;
+  onOpen?: (id: string) => void;
+  className?: string;
+}
+
+/** Compact single-line chip for a day marker. */
+export function DayChip({ marker, onOpen, className }: DayChipProps) {
+  return (
+    <button
+      type="button"
+      onClick={onOpen ? () => onOpen(marker.id) : undefined}
+      className={cn(
+        "block w-full truncate rounded-xs px-1.5 py-0.5 text-left text-chip-text",
+        TONE[marker.tone ?? "accent"],
+        className,
+      )}
+    >
+      {marker.srLabel ? <span className="sr-only">{marker.srLabel} </span> : null}
+      {marker.title}
+      {marker.subtitle ? (
+        <span className="font-normal opacity-80"> · {marker.subtitle}</span>
+      ) : null}
+    </button>
+  );
+}

package/src/calendar/day-chip/index.ts

@@ -0,0 +1,2 @@
+export type { CalendarMarker } from "../internal/types.js";
+export { DayChip, type DayChipProps } from "./day-chip.js";

package/src/calendar/event-block/event-block.tsx

@@ -0,0 +1,74 @@
+import { cn } from "../../utils/cn.js";
+import type { CalendarEvent, CalendarTone } from "../internal/types.js";
+
+const TONE: Record<CalendarTone, string> = {
+  accent: "bg-accent-soft border-accent-line",
+  neutral: "bg-surface-2 border-line-strong",
+  success: "bg-success-soft border-success/35",
+  danger: "bg-danger-soft border-danger/40",
+  warning: "bg-warning-soft border-warning/40",
+};
+
+export interface EventBlockProps {
+  event: CalendarEvent;
+  /** "detailed": time range, title and subtitle. "compact": one "time title" line. */
+  variant?: "detailed" | "compact";
+  onOpen?: (id: string) => void;
+  className?: string;
+}
+
+export function EventBlock({ event, variant = "detailed", onOpen, className }: EventBlockProps) {
+  const tone = TONE[event.tone ?? "accent"];
+  const range = event.end ? `${event.start}–${event.end}` : event.start;
+  const srLabel = event.srLabel ? <span className="sr-only">{event.srLabel} </span> : null;
+  const handleClick = onOpen ? () => onOpen(event.id) : undefined;
+
+  if (variant === "compact") {
+    return (
+      <button
+        type="button"
+        onClick={handleClick}
+        className={cn(
+          "block w-full truncate rounded-xs border px-1.5 py-0.5 text-left text-chip-text text-ink",
+          tone,
+          className,
+        )}
+      >
+        {srLabel}
+        {event.start} {event.title}
+      </button>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={cn(
+        "@container/event block w-full min-w-0 overflow-hidden rounded-event border px-2.5 py-2 text-left",
+        tone,
+        className,
+      )}
+    >
+      {srLabel}
+      <span
+        className={cn(
+          "grid h-full grid-cols-[96px_minmax(0,1fr)_auto] items-center gap-x-2.5",
+          "@max-[28rem]/event:grid-cols-[70px_minmax(0,1fr)]",
+          "@max-[9rem]/event:grid-cols-[minmax(0,1fr)] @max-[9rem]/event:gap-y-0.5",
+        )}
+      >
+        <span className="whitespace-nowrap font-mono text-meta text-ink-2">{range}</span>
+        <span className="min-w-0">
+          <span className="block truncate text-row-title text-ink">{event.title}</span>
+          {event.subtitle ? (
+            <span className="block truncate text-meta text-ink-3">{event.subtitle}</span>
+          ) : null}
+        </span>
+        {event.trailing ? (
+          <span className="@max-[28rem]/event:hidden">{event.trailing}</span>
+        ) : null}
+      </span>
+    </button>
+  );
+}

package/src/calendar/event-block/index.ts

@@ -0,0 +1,2 @@
+export type { CalendarEvent, CalendarTone } from "../internal/types.js";
+export { EventBlock, type EventBlockProps } from "./event-block.js";

package/src/calendar/index.ts

@@ -0,0 +1,5 @@
+export * from "./day-chip/index.js";
+export * from "./event-block/index.js";
+export * from "./month-view/index.js";
+export * from "./timeline-view/index.js";
+export * from "./week-view/index.js";

package/src/calendar/internal/date-utils.ts

@@ -0,0 +1,78 @@
+/** Calendar-date helpers. Dates are "YYYY-MM-DD" strings handled in UTC so they never shift by time zone. */
+
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export function parseDate(value: string): Date {
+  const [year, month, day] = value.split("-").map(Number);
+  return new Date(Date.UTC(year ?? 1970, (month ?? 1) - 1, day ?? 1));
+}
+
+export function formatDate(date: Date): string {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function addDays(value: string, amount: number): string {
+  const date = parseDate(value);
+  return formatDate(
+    new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount)),
+  );
+}
+
+/** First day of the week containing `value`; `weekStartsOn` is 0 (Sunday) to 6 (Saturday). */
+export function startOfWeek(value: string, weekStartsOn: WeekStart = 1): string {
+  const offset = (parseDate(value).getUTCDay() - weekStartsOn + 7) % 7;
+  return addDays(value, -offset);
+}
+
+/** Full weeks (7 columns) covering the month that contains `value`. */
+export function monthGrid(value: string, weekStartsOn: WeekStart = 1): string[] {
+  const target = parseDate(value);
+  const month = target.getUTCMonth();
+  const first = formatDate(new Date(Date.UTC(target.getUTCFullYear(), month, 1)));
+  const last = formatDate(new Date(Date.UTC(target.getUTCFullYear(), month + 1, 0)));
+  const start = startOfWeek(first, weekStartsOn);
+  const end = addDays(startOfWeek(last, weekStartsOn), 6);
+  const days: string[] = [];
+  for (let day = start; day <= end; day = addDays(day, 1)) days.push(day);
+  return days;
+}
+
+export function minutesSinceMidnight(time: string): number {
+  const [hours, minutes] = time.split(":").map(Number);
+  return (hours ?? 0) * 60 + (minutes ?? 0);
+}
+
+function format(
+  value: string,
+  locale: string | undefined,
+  options: Intl.DateTimeFormatOptions,
+): string {
+  return new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" }).format(parseDate(value));
+}
+
+/** Localized short weekday name, e.g. "Mon". */
+export function formatWeekday(value: string, locale?: string): string {
+  return format(value, locale, { weekday: "short" });
+}
+
+/** Localized short weekday followed by the day number, e.g. "Mon 12". */
+export function formatWeekdayAndDay(value: string, locale?: string): string {
+  return `${formatWeekday(value, locale)} ${parseDate(value).getUTCDate()}`;
+}
+
+/** Localized short month name, e.g. "Jan". */
+export function formatMonthShort(value: string, locale?: string): string {
+  return format(value, locale, { month: "short" });
+}
+
+/** Localized hour label for an hour of the day (0-23). */
+export function formatHour(hour: number, locale?: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZone: "UTC",
+  }).format(new Date(Date.UTC(1970, 0, 1, hour)));
+}

package/src/calendar/internal/index.ts

@@ -0,0 +1,3 @@
+export * from "./date-utils.js";
+export * from "./layout.js";
+export * from "./types.js";

package/src/calendar/internal/layout.ts

@@ -0,0 +1,60 @@
+import { minutesSinceMidnight } from "./date-utils.js";
+import type { CalendarEvent } from "./types.js";
+
+/** Minimum duration (minutes) for an event without an end time. */
+const MIN_DURATION = 30;
+
+export interface TimedEvent {
+  event: CalendarEvent;
+  start: number;
+  end: number;
+}
+
+export interface PositionedEvent extends TimedEvent {
+  /** 0-based column inside its group of overlapping events. */
+  column: number;
+  /** Number of columns in the group, used to split the width. */
+  columns: number;
+}
+
+function toMinutes(events: CalendarEvent[]): TimedEvent[] {
+  return events.map((event) => {
+    const start = minutesSinceMidnight(event.start);
+    const end = event.end ? minutesSinceMidnight(event.end) : start + MIN_DURATION;
+    return { event, start, end: Math.max(end, start + 1) };
+  });
+}
+
+/** Greedy column assignment for overlapping events of one day. */
+export function layoutDayEvents(events: CalendarEvent[]): PositionedEvent[] {
+  const sorted = toMinutes(events).sort((a, b) => a.start - b.start || a.end - b.end);
+  const positioned: PositionedEvent[] = [];
+  let group: PositionedEvent[] = [];
+  let groupEnd = Number.NEGATIVE_INFINITY;
+
+  const closeGroup = () => {
+    const columns = group.reduce((max, item) => Math.max(max, item.column + 1), 0);
+    for (const item of group) {
+      item.columns = columns;
+      positioned.push(item);
+    }
+    group = [];
+  };
+
+  for (const item of sorted) {
+    if (group.length > 0 && item.start >= groupEnd) {
+      closeGroup();
+      groupEnd = Number.NEGATIVE_INFINITY;
+    }
+    const columnEnds: number[] = [];
+    for (const previous of group) {
+      columnEnds[previous.column] = Math.max(columnEnds[previous.column] ?? 0, previous.end);
+    }
+    let column = columnEnds.findIndex((end) => end <= item.start);
+    if (column === -1) column = columnEnds.length;
+    group.push({ ...item, column, columns: 0 });
+    groupEnd = Math.max(groupEnd, item.end);
+  }
+  closeGroup();
+  return positioned;
+}

package/src/calendar/internal/styles.ts

@@ -0,0 +1,3 @@
+/** Diagonal hatch used to shade non-working days. */
+export const SHADED_DAY_CLASS =
+  "bg-[repeating-linear-gradient(135deg,var(--hatch)_0_3px,transparent_3px_7px)]";

package/src/calendar/internal/types.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+
+/** Visual tone shared by events and markers. */
+export type CalendarTone = "accent" | "neutral" | "success" | "danger" | "warning";
+
+/** A calendar event. Dates are ISO calendar dates ("YYYY-MM-DD"), times are "HH:mm". */
+export interface CalendarEvent {
+  id: string;
+  date: string;
+  start: string;
+  end?: string;
+  title: string;
+  subtitle?: string;
+  tone?: CalendarTone;
+  /** Screen-reader-only text announced before the title (e.g. the event kind). */
+  srLabel?: string;
+  /** All-day events render in the week view's top row instead of the hour grid. */
+  allDay?: boolean;
+  /** Optional node rendered at the end of the detailed block (e.g. an avatar). */
+  trailing?: ReactNode;
+}
+
+/** A single-day marker rendered as a chip (deadline, reminder, holiday...). */
+export interface CalendarMarker {
+  id: string;
+  date: string;
+  title: string;
+  subtitle?: string;
+  tone?: "danger" | "accent";
+  /** Screen-reader-only text announced before the title. */
+  srLabel?: string;
+}

package/src/calendar/month-view/index.ts

@@ -0,0 +1 @@
+export { MonthView, type MonthViewProps } from "./month-view.js";

package/src/calendar/month-view/month-view.tsx

@@ -0,0 +1,157 @@
+import { cn } from "../../utils/cn.js";
+import { DayChip } from "../day-chip/index.js";
+import { EventBlock } from "../event-block/index.js";
+import { formatWeekday, monthGrid, parseDate, type WeekStart } from "../internal/date-utils.js";
+import { SHADED_DAY_CLASS } from "../internal/styles.js";
+import type { CalendarEvent, CalendarMarker, CalendarTone } from "../internal/types.js";
+
+const MAX_VISIBLE_ITEMS = 3;
+
+const DOT_TONE: Record<CalendarTone, string> = {
+  accent: "bg-accent",
+  neutral: "bg-ink-3",
+  success: "bg-success",
+  danger: "bg-danger",
+  warning: "bg-warning",
+};
+
+type DayItem = { kind: "marker"; item: CalendarMarker } | { kind: "event"; item: CalendarEvent };
+
+export interface MonthViewProps {
+  /** Any "YYYY-MM-DD" date inside the month to show. */
+  month: string;
+  /** "YYYY-MM-DD" date highlighted as today; the view never computes it. */
+  today: string;
+  events: CalendarEvent[];
+  markers?: CalendarMarker[];
+  /** Dates ("YYYY-MM-DD") rendered with a hatch pattern (non-working days). */
+  shadedDates?: string[];
+  /** BCP 47 locale for weekday labels. Defaults to the runtime locale. */
+  locale?: string;
+  /** First day of the week, 0 (Sunday) to 6 (Saturday). Defaults to 1 (Monday). */
+  weekStartsOn?: WeekStart;
+  /** Label for the overflow button, e.g. `(n) => \`+${n} more\``. */
+  formatMore: (count: number) => string;
+  onOpenEvent?: (id: string) => void;
+  onOpenMarker?: (id: string) => void;
+  /** Called with the day's date when the overflow button is clicked. */
+  onSelectDate?: (date: string) => void;
+  className?: string;
+}
+
+export function MonthView({
+  month,
+  today,
+  events,
+  markers = [],
+  shadedDates = [],
+  locale,
+  weekStartsOn = 1,
+  formatMore,
+  onOpenEvent,
+  onOpenMarker,
+  onSelectDate,
+  className,
+}: MonthViewProps) {
+  const monthIndex = parseDate(month).getUTCMonth();
+  const days = monthGrid(month, weekStartsOn);
+  const shaded = new Set(shadedDates);
+
+  return (
+    <div className={cn("@container/month grid min-w-0 grid-cols-7", className)}>
+      {days.slice(0, 7).map((date) => (
+        <div
+          key={date}
+          className="min-w-0 truncate border-b-divider px-2.5 py-2 text-overline text-ink-3 @max-[40rem]/month:px-0.5 @max-[40rem]/month:text-center"
+        >
+          {formatWeekday(date, locale)}
+        </div>
+      ))}
+      {days.map((date) => {
+        const parsed = parseDate(date);
+        const outside = parsed.getUTCMonth() !== monthIndex;
+        const isToday = date === today;
+        const items: DayItem[] = [
+          ...markers
+            .filter((marker) => marker.date === date)
+            .map((item): DayItem => ({ kind: "marker", item })),
+          ...events
+            .filter((event) => event.date === date)
+            .map((item): DayItem => ({ kind: "event", item })),
+        ];
+        const visible = items.slice(0, MAX_VISIBLE_ITEMS);
+        const hidden = items.length - visible.length;
+
+        return (
+          <div
+            key={date}
+            data-date={date}
+            data-today={isToday || undefined}
+            data-outside-month={outside || undefined}
+            data-shaded={shaded.has(date) || undefined}
+            className={cn(
+              "flex min-h-30 min-w-0 flex-col gap-0.75 border-b-divider border-l-divider p-1.5 @max-[40rem]/month:min-h-16 @max-[40rem]/month:items-center @max-[40rem]/month:p-0.5",
+              shaded.has(date) && SHADED_DAY_CLASS,
+              outside && "opacity-45",
+            )}
+          >
+            <span
+              className={cn(
+                "grid h-5.5 min-w-6 place-items-center self-start rounded-xs font-mono text-chip-text text-ink-2",
+                isToday && "bg-accent text-on-accent",
+              )}
+            >
+              {parsed.getUTCDate()}
+            </span>
+            <div className="flex min-w-0 flex-col gap-0.75 @max-[40rem]/month:hidden">
+              {visible.map(({ kind, item }) =>
+                kind === "marker" ? (
+                  <DayChip key={item.id} marker={item} onOpen={onOpenMarker} />
+                ) : (
+                  <EventBlock key={item.id} event={item} variant="compact" onOpen={onOpenEvent} />
+                ),
+              )}
+              {hidden > 0 ? (
+                <button
+                  type="button"
+                  onClick={onSelectDate ? () => onSelectDate(date) : undefined}
+                  className="px-1.5 text-left text-chip-text text-ink-3"
+                >
+                  {formatMore(hidden)}
+                </button>
+              ) : null}
+            </div>
+            {items.length > 0 ? (
+              <div className="hidden flex-wrap justify-center gap-0.5 @max-[40rem]/month:flex">
+                {items.map(({ kind, item }) => (
+                  <button
+                    key={item.id}
+                    type="button"
+                    aria-label={item.title}
+                    onClick={
+                      kind === "marker"
+                        ? onOpenMarker
+                          ? () => onOpenMarker(item.id)
+                          : undefined
+                        : onOpenEvent
+                          ? () => onOpenEvent(item.id)
+                          : undefined
+                    }
+                    className={cn(
+                      "size-2 rounded-avatar p-0",
+                      kind === "marker"
+                        ? item.tone === "danger"
+                          ? DOT_TONE.danger
+                          : DOT_TONE.accent
+                        : DOT_TONE[item.tone ?? "accent"],
+                    )}
+                  />
+                ))}
+              </div>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/calendar/timeline-view/index.ts

@@ -0,0 +1 @@
+export { TimelineView, type TimelineViewProps } from "./timeline-view.js";