@lotics/ui 47.13.1 → 47.15.0

package/src/cell_stack.tsx

@@ -11,6 +11,12 @@ export interface CellStackProps {
    *
    * One, not several: a stack of three is no longer a value and its annotation,
    * it is a row that wants to be a row.
+   *
+   * To RESERVE the line on a row that has nothing to say — which is how a column
+   * whose cells are sometimes two lines keeps one first-line height down the page
+   * (probe 8h-bis) — pass a whitespace string. `" "` is what everybody writes and
+   * the web renderer collapses it, so it is normalised to a non-breaking space
+   * here rather than in twelve call sites.
    */
   caption?: ReactNode;
   /**
@@ -24,6 +30,13 @@ export interface CellStackProps {
    * does, so the caption keeps body size beside one.
    */
   marked?: boolean;
+  /**
+   * The identity mark, drawn HERE — an `Avatar`, a `FileBadge`. Sets `marked`
+   * and owns the gap between the mark and the pair, so a register's subject
+   * column is not one more hand-rolled row of mark + stack with its own idea
+   * of the gap. The column still budgets the mark's width (`TableColumn.lead`).
+   */
+  leading?: ReactNode;
   /** The subject's rung. The pair takes ONE rung, so the caption follows it. */
   size?: TextSize;
   /** The subject's ink. The caption is always `muted` — it is supporting text. */
@@ -80,7 +93,8 @@ export function CellStack(props: CellStackProps) {
     title,
     caption,
     weight = "regular",
-    marked = false,
+    marked: markedProp = false,
+    leading,
     size = "sm",
     color,
     tabular,
@@ -90,7 +104,16 @@ export function CellStack(props: CellStackProps) {
     testID,
   } = props;
 
-  const hasCaption = caption !== undefined && caption !== null && caption !== false;
+  // A caption reserving the line with nothing in it. `" "` says "keep this line"
+  // unambiguously and collapses in the web renderer, so the reserved line loses
+  // its height and the cell drops to ONE line — while the row height, set by
+  // whichever sibling is two lines tall, never moves. The column then puts its
+  // first line at two different heights on rows that look identical to every
+  // spacing probe. One app wrote it twelve times.
+  const line = typeof caption === "string" && caption.length > 0 && caption.trim() === "" ? NBSP : caption;
+  const hasCaption = line !== undefined && line !== null && line !== false;
+  const hasLeading = leading !== undefined && leading !== null && leading !== false;
+  const marked = markedProp || hasLeading;
   // Rule 1 — the caption's rung, from what else is already separating the pair.
   const captionSize: TextSize = weight !== "regular" || marked ? size : "xs";
   // Rule 2 — tight closes a PAIR; `xs` is tight by construction, and a lone line
@@ -98,8 +121,8 @@ export function CellStack(props: CellStackProps) {
   const subjectTight = hasCaption ? "tight" : undefined;
   const captionTight = captionSize === "xs" ? undefined : "tight";
 
-  return (
-    <View style={[{ gap: 0, alignItems: ALIGN[align] }, style]} testID={testID}>
+  const stack = (
+    <View style={[{ gap: 0, alignItems: ALIGN[align] }, hasLeading ? { flex: 1, minWidth: 0 } : style]} testID={hasLeading ? undefined : testID}>
       {typeof title === "string" || typeof title === "number" ? (
         <Text
           size={size}
@@ -115,7 +138,7 @@ export function CellStack(props: CellStackProps) {
         title
       )}
       {hasCaption
-        ? typeof caption === "string" || typeof caption === "number"
+        ? typeof line === "string" || typeof line === "number"
           ? (
             <Text
               size={captionSize}
@@ -124,15 +147,28 @@ export function CellStack(props: CellStackProps) {
               tabular={tabular}
               numberOfLines={numberOfLines}
             >
-              {caption}
+              {line}
             </Text>
           )
-          : caption
+          : line
         : null}
     </View>
   );
+  if (!hasLeading) return stack;
+  return (
+    <View style={[{ flexDirection: "row", alignItems: "center", gap: LEADING_GAP, minWidth: 0 }, style]} testID={testID}>
+      {leading}
+      {stack}
+    </View>
+  );
 }
 
+const NBSP = "\u00a0";
+
+/** Mark to pair \u2014 the ONE gap between an identity mark and the label beside it,
+ *  wherever the kit draws that pair (`CellStack`, `Matrix`, `StateMatrix`). */
+export const LEADING_GAP = 10;
+
 const ALIGN = {
   left: "flex-start",
   right: "flex-end",

package/src/chip_group.tsx

@@ -147,12 +147,18 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
                 color={option.iconColor ?? (active ? colors.zinc[900] : colors.zinc[500])}
               />
             ) : null}
-            <Text
-              userSelect="none"
-              size="sm"
-              weight={active ? "semibold" : "medium"}
-              color={active ? "default" : "muted"}
-            >
+            {/* MEDIUM on both, never semibold on the active one.
+
+                A chip already answers "which one is on" twice — a doubled
+                zinc-900 edge and a ring — so the weight was a third signal, and
+                the wrong kind: semibold is a separate, genuinely heavier FILE
+                and the heading ramp is semibold at every rung, so an active chip
+                rendered a filter value at heading weight. State steps up in INK,
+                which is what `color` does here. It also made the active chip a
+                singleton treatment on every screen carrying one, while the
+                sibling that answers the same question — `Tabs` — steps
+                regular → medium. One question, one answer. */}
+            <Text userSelect="none" size="sm" weight="medium" color={active ? "default" : "muted"}>
               {option.label}
             </Text>
             {option.count != null ? (

package/src/danger_zone.tsx

@@ -23,24 +23,32 @@ export interface DangerZoneProps {
  * a danger heading mark it as a hazard without shouting (the kit's `tint`/`solid`
  * discipline, never a raw hex); the consequence goes in `description`, and the
  * action(s) go in `children`.
+ *
+ * ONE LEFT EDGE, and it is `Callout`'s anatomy that gets it: the icon sits in an
+ * outer ROW beside a column holding title, consequence and actions, so all three
+ * derive from the same edge. Put the icon INSIDE the heading row instead — the
+ * obvious way to write it — and only the TITLE moves right, so the loudest line
+ * in the block sits 22px past the sentence explaining it and the button under
+ * both starts somewhere else again. Three edges inside one 16px-padded box, on
+ * the one primitive that exists so a hazard is not hand-rolled.
  */
 export function DangerZone(props: DangerZoneProps) {
   const locale = useLoticsLocale();
   const { title = locale.dangerZone.title, description, children } = props;
   return (
     <View style={styles.zone}>
-      <View style={styles.heading}>
-        <Icon name="triangle-alert" size={16} color={solid("red")} />
+      <Icon name="triangle-alert" size={16} color={solid("red")} />
+      <View style={styles.body}>
         <Text size="sm" weight="semibold" color="danger">
           {title}
         </Text>
+        {description ? (
+          <Text size="sm" color="muted">
+            {description}
+          </Text>
+        ) : null}
+        <View style={styles.actions}>{children}</View>
       </View>
-      {description ? (
-        <Text size="sm" color="muted">
-          {description}
-        </Text>
-      ) : null}
-      <View style={styles.actions}>{children}</View>
     </View>
   );
 }
@@ -49,13 +57,18 @@ const styles = StyleSheet.create({
   // A soft danger frame: a low-alpha red hairline over the faintest red wash —
   // the "set apart, not shouting" treatment via the kit's tint discipline.
   zone: {
-    gap: 8,
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: 10,
     padding: 16,
     borderRadius: 10,
     borderWidth: 1,
     borderColor: tint("red", 0.3),
     backgroundColor: tint("red", 0.03),
   },
-  heading: { flexDirection: "row", alignItems: "center", gap: 6 },
+  // The column every line in the block starts from — 1px down so the first line
+  // of type sits optically level with the 16px mark beside it, exactly as
+  // `Callout` does it.
+  body: { flex: 1, gap: 8, paddingTop: 1 },
   actions: { flexDirection: "row", flexWrap: "wrap", gap: 8, marginTop: 4 },
 });

package/src/date_filter.tsx

@@ -33,6 +33,10 @@ export interface DateFilterLabels extends SegmentLabels {
   thisWeek: string;
   thisMonth: string;
   lastMonth: string;
+  thisQuarter: string;
+  lastQuarter: string;
+  thisYear: string;
+  lastYear: string;
   from: string;
   to: string;
   /** Accessible name of the field that OPENS this panel (`DateRangeFilterField`). */
@@ -71,6 +75,14 @@ function presetLabel(id: PresetId, labels: DateFilterLabels): string {
       return labels.thisMonth;
     case "last_month":
       return labels.lastMonth;
+    case "this_quarter":
+      return labels.thisQuarter;
+    case "last_quarter":
+      return labels.lastQuarter;
+    case "this_year":
+      return labels.thisYear;
+    case "last_year":
+      return labels.lastYear;
   }
 }
 
@@ -224,12 +236,10 @@ export function DateFilter(props: DateFilterProps) {
     (id: PresetId) => {
       // A preset replaces the whole range, so any half-picked start is abandoned.
       setPendingStart(null);
-      // Re-clicking the active preset clears the filter
-      if (activePresetId === id) {
-        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
-        return;
-      }
-
+      // Resolved against today on EVERY press, the active one included: a preset
+      // names a period, so re-pressing it re-anchors a range that has gone stale
+      // (a panel left open across midnight) rather than doing nothing. Clearing
+      // is the footer's Clear button — this list holds no null case.
       const presetValue = getPresetValue(id, new Date());
       onValueChange(presetValue);
 
@@ -240,7 +250,7 @@ export function DateFilter(props: DateFilterProps) {
         );
       }
     },
-    [onValueChange, activePresetId],
+    [onValueChange],
   );
 
   // `selected` + `role="option"` is the kit's listbox row, and `MenuButton` owns

package/src/date_filter_presets.ts

@@ -10,7 +10,11 @@ export type PresetId =
   | "tomorrow"
   | "this_week"
   | "this_month"
-  | "last_month";
+  | "last_month"
+  | "this_quarter"
+  | "last_quarter"
+  | "this_year"
+  | "last_year";
 
 /**
  * Display order. Every id here SETS a range — that is what makes the list a set
@@ -22,6 +26,9 @@ export type PresetId =
  * the obvious move for "let me pick my own dates", threw the range away. The
  * calendar above it is the custom picker, and the panel's Clear button is the
  * clear; the item was a third name for two controls that were already there.
+ *
+ * Ordered by GRAIN, shortest first — a reader scanning for "this quarter"
+ * looks past the days and the month rather than hunting an alphabetical list.
  */
 export const PRESET_IDS: PresetId[] = [
   "today",
@@ -30,6 +37,10 @@ export const PRESET_IDS: PresetId[] = [
   "this_week",
   "this_month",
   "last_month",
+  "this_quarter",
+  "last_quarter",
+  "this_year",
+  "last_year",
 ];
 
 function startOfDay(date: Date): Date {
@@ -73,6 +84,27 @@ function range(start: Date, end: Date): DateFilterValue {
   return { start: { date: start, time: null }, end: { date: end, time: null } };
 }
 
+/** The 0-based quarter a month falls in. */
+function quarterOf(date: Date): number {
+  return Math.floor(date.getMonth() / 3);
+}
+
+/**
+ * The whole quarter `q` (0-based) of `year`, as a range.
+ *
+ * Built from the quarter INDEX rather than by shifting a date three months:
+ * `setMonth(getMonth() - 3)` on the 31st of a month lands in the month after
+ * the one meant (31 May → 31 February → 3 March), and the quarter then comes
+ * out one too late for every long month.
+ */
+function quarterRange(year: number, q: number): DateFilterValue {
+  return range(new Date(year, q * 3, 1), new Date(year, q * 3 + 3, 0, 23, 59, 59, 999));
+}
+
+function yearRange(year: number): DateFilterValue {
+  return range(new Date(year, 0, 1), new Date(year, 11, 31, 23, 59, 59, 999));
+}
+
 /**
  * Resolve a preset to a concrete date range relative to `now`. Total — every
  * `PresetId` names a range. The boundary math is identical to the view-page
@@ -101,5 +133,181 @@ export function getPresetValue(id: PresetId, now: Date): DateFilterValue {
       d.setMonth(d.getMonth() - 1);
       return range(startOfMonth(d), endOfMonth(d));
     }
+    case "this_quarter":
+      return quarterRange(now.getFullYear(), quarterOf(now));
+    case "last_quarter": {
+      const q = quarterOf(now) - 1;
+      return q < 0 ? quarterRange(now.getFullYear() - 1, 3) : quarterRange(now.getFullYear(), q);
+    }
+    case "this_year":
+      return yearRange(now.getFullYear());
+    case "last_year":
+      return yearRange(now.getFullYear() - 1);
   }
 }
+
+const DAY_MS = 86_400_000;
+
+function isWholeMonth(start: Date, end: Date): boolean {
+  return (
+    start.getDate() === 1 &&
+    start.getFullYear() === end.getFullYear() &&
+    start.getMonth() === end.getMonth() &&
+    end.getDate() === new Date(end.getFullYear(), end.getMonth() + 1, 0).getDate()
+  );
+}
+
+function isWholeQuarter(start: Date, end: Date): boolean {
+  return (
+    start.getDate() === 1 &&
+    start.getMonth() % 3 === 0 &&
+    start.getFullYear() === end.getFullYear() &&
+    end.getMonth() === start.getMonth() + 2 &&
+    end.getDate() === new Date(end.getFullYear(), end.getMonth() + 1, 0).getDate()
+  );
+}
+
+function isWholeYear(start: Date, end: Date): boolean {
+  return (
+    start.getFullYear() === end.getFullYear() &&
+    start.getMonth() === 0 &&
+    start.getDate() === 1 &&
+    end.getMonth() === 11 &&
+    end.getDate() === 31
+  );
+}
+
+/**
+ * THE COMPARATOR for a selected range — the period a report means by "so với kỳ
+ * trước". Derived from the range the reader already picked, so a dashboard needs
+ * no second control beside its date field to say what it is comparing against.
+ *
+ * A range that IS a whole calendar month, quarter or year steps back one WHOLE
+ * period, never a fixed number of days: February against March is 28 days
+ * against 31, and sliding a 31-day window back would compare March against the
+ * last three days of January plus February. Any other complete range — a
+ * hand-picked fortnight, a week — steps back by its own LENGTH, ending the day
+ * before it starts, so two adjacent windows of equal size are compared.
+ *
+ * Whole days only. The bounds come back day-aligned and untimed, matching the
+ * presets, because a period comparison is a comparison of periods; a timed
+ * window has no previous one to speak of. `null` when either bound is missing —
+ * an open range names no period, and a comparator invented for one would be a
+ * figure the reader never asked for.
+ */
+export function previousPeriod(value: DateFilterValue): DateFilterValue | null {
+  const { date: startDate } = value.start;
+  const { date: endDate } = value.end;
+  if (!startDate || !endDate) return null;
+
+  const start = startOfDay(startDate);
+  const end = startOfDay(endDate);
+
+  if (isWholeYear(start, end)) return yearRange(start.getFullYear() - 1);
+  if (isWholeQuarter(start, end)) {
+    const q = quarterOf(start) - 1;
+    return q < 0 ? quarterRange(start.getFullYear() - 1, 3) : quarterRange(start.getFullYear(), q);
+  }
+  if (isWholeMonth(start, end)) {
+    const d = new Date(start.getFullYear(), start.getMonth() - 1, 1);
+    return range(startOfMonth(d), endOfMonth(d));
+  }
+
+  // Rounded, not floored: a range spanning a DST change is 23 or 25 hours short
+  // of a whole number of days, and a floor would silently drop one from it.
+  const days = Math.round((end.getTime() - start.getTime()) / DAY_MS) + 1;
+  const prevEnd = new Date(start);
+  prevEnd.setDate(prevEnd.getDate() - 1);
+  const prevStart = new Date(prevEnd);
+  prevStart.setDate(prevStart.getDate() - (days - 1));
+  return range(startOfDay(prevStart), endOfDay(prevEnd));
+}
+
+/** A selected period read against the clock, with its comparator already cut. */
+export interface PeriodToDate {
+  /** The selection, ending at `now` while the period is still RUNNING. */
+  current: DateFilterValue;
+  /** `previousPeriod`, cut to the same elapsed days. `null` when the selection
+   *  is open-ended and so names no period to step back from. */
+  previous: DateFilterValue | null;
+  /** `now` falls before the selection's last day. */
+  running: boolean;
+  /** Days of the selection already behind us — 0 for a period still ahead. */
+  elapsedDays: number;
+  /** Days the whole selection holds, elapsed or not. */
+  totalDays: number;
+}
+
+/** Whole days between two day-aligned dates, inclusive. Rounded for the reason
+ *  `previousPeriod` rounds: a DST change makes a span 23 or 25 hours. */
+function dayCount(from: Date, to: Date): number {
+  return Math.round((to.getTime() - from.getTime()) / DAY_MS) + 1;
+}
+
+function addDays(date: Date, days: number): Date {
+  const d = new Date(date);
+  d.setDate(d.getDate() + days);
+  return d;
+}
+
+/**
+ * A RUNNING period is compared TO DATE: both sides cut to the days that have
+ * actually elapsed.
+ *
+ * Six days of this month placed beside a whole previous month reads as a
+ * collapse that never happened, and it lands on the first figure anyone looks
+ * at. So the selection ends at `now` while it is still running, and the
+ * comparator `previousPeriod` names is cut to the same count from ITS first
+ * day — six days against the first six, a quarter's 68 days against the
+ * previous quarter's first 68. The cut is clamped to the previous period's own
+ * end, so thirty elapsed days of March compare against all 28 of February
+ * rather than running past it.
+ *
+ * A period already closed keeps both sides whole. A period entirely in the
+ * future has nothing elapsed: `current` holds its first day and `elapsedDays`
+ * is 0, so a caller can say it has not started instead of drawing a −100%.
+ *
+ * `null` when either bound is missing, matching `previousPeriod`.
+ */
+export function periodToDate(value: DateFilterValue, now: Date): PeriodToDate | null {
+  const { date: startDate } = value.start;
+  const { date: endDate } = value.end;
+  if (!startDate || !endDate) return null;
+
+  const from = startOfDay(startDate);
+  const to = startOfDay(endDate);
+  const today = startOfDay(now);
+  const totalDays = dayCount(from, to);
+  const whole = previousPeriod(value);
+
+  if (today.getTime() >= to.getTime()) {
+    return {
+      current: range(from, endOfDay(to)),
+      previous: whole,
+      running: false,
+      elapsedDays: totalDays,
+      totalDays,
+    };
+  }
+
+  const elapsedDays = today.getTime() < from.getTime() ? 0 : dayCount(from, today);
+  const previous = (() => {
+    const prevStart = whole?.start.date;
+    const prevEnd = whole?.end.date;
+    if (!prevStart || !prevEnd) return null;
+    const opens = startOfDay(prevStart);
+    const closes = startOfDay(prevEnd);
+    // `max(elapsed, 1)`: a period not yet begun still names one day on each
+    // side, so the pair has the same shape whichever side of `now` it sits.
+    const cut = addDays(opens, Math.max(elapsedDays, 1) - 1);
+    return range(opens, endOfDay(cut.getTime() > closes.getTime() ? closes : cut));
+  })();
+
+  return {
+    current: range(from, endOfDay(elapsedDays === 0 ? from : today)),
+    previous,
+    running: true,
+    elapsedDays,
+    totalDays,
+  };
+}

package/src/date_range_filter_field.tsx

@@ -63,20 +63,30 @@ function formatBound(date: Date | null, time: string | null, locale: string | un
 /**
  * Recognized whole periods display compactly — a range that IS a calendar
  * month reads "Tháng 6 năm 2026" (sentence-cased via the locale), a whole
- * year "2026", a single day one date. Anything else falls back to
- * "start – end". Keeps the trigger scannable where dashboards live in
- * period rhythm, not date pairs.
+ * quarter "Quý 2 năm 2026", a whole year "2026", a single day one date.
+ * Anything else falls back to "start – end". Keeps the trigger scannable where
+ * dashboards live in period rhythm, not date pairs.
  */
 function formatRangeDisplay(start: Date, end: Date, locale: string | undefined): string {
   if (start.toDateString() === end.toDateString()) return formatDate(start, { locale });
 
+  const lastDayOfEndMonth = new Date(end.getFullYear(), end.getMonth() + 1, 0).getDate();
+
   const wholeMonth =
     start.getDate() === 1 &&
     start.getMonth() === end.getMonth() &&
     start.getFullYear() === end.getFullYear() &&
-    end.getDate() === new Date(end.getFullYear(), end.getMonth() + 1, 0).getDate();
+    end.getDate() === lastDayOfEndMonth;
   if (wholeMonth) return formatDate(start, { format: "monthYear", locale });
 
+  const wholeQuarter =
+    start.getDate() === 1 &&
+    start.getMonth() % 3 === 0 &&
+    start.getFullYear() === end.getFullYear() &&
+    end.getMonth() === start.getMonth() + 2 &&
+    end.getDate() === lastDayOfEndMonth;
+  if (wholeQuarter) return formatDate(start, { format: "quarterYear", locale });
+
   const wholeYear =
     start.getFullYear() === end.getFullYear() &&
     start.getMonth() === 0 &&

package/src/detail_row.tsx

@@ -167,32 +167,32 @@ export function DetailRow(props: DetailRowProps) {
   // thing on two surfaces; they may not say a fault two different ways.
   const annotations = <FieldAnnotations description={description} warning={warning} error={error} flat={flat} />;
   if (table?.stacked) {
-    // Stacked mode wears the FORM grammar: the label renders exactly like a
-    // `FormField` label (medium, default ink), so a narrow record surface
-    // reads as one vocabulary with forms. The COMPONENTS stay separate — a
-    // FormField wraps a draft control validated and committed together, an
-    // inline editor self-persists — only the look converges.
+    // Stacked mode wears the form LOOK — the label renders like a `FormField`
+    // label (medium, default ink), so a narrow record surface reads as one
+    // vocabulary with forms — but keeps the RECORD's reading order: label,
+    // value, then whatever has to be said about it.
+    //
+    // Not the form ORDER, which puts the description above the control. A form's
+    // description is guidance you need BEFORE typing; a record's qualifies a
+    // value that already exists, so ahead of it the reader gets "còn 116 ngày"
+    // before any date and "con số là cho cả hợp đồng" before any con số. Reading
+    // a caption before its subject is not one job per element, and it made one
+    // row read two ways at two widths — the horizontal branch has always put
+    // annotations UNDER the value.
+    //
+    // The annotations are the shared `FieldAnnotations` anatomy, the same one
+    // the horizontal branch renders, so a fault says itself one way at both
+    // widths — hand-rolled here they came out a rung larger and off the
+    // control's own text inset.
     return (
       <View style={styles.stackedRow}>
         {/* Wraps, like the horizontal label — a stacked row has the FULL width
             to spend, so clipping here would be gratuitous. */}
         <Text weight="medium">{label}</Text>
-        {/* stacked wears the FORM grammar exactly: label, description,
-            control, warning, error (the `FormField` order) */}
-        {description != null ? <Text color="muted">{description}</Text> : null}
         <View style={[styles.stackedValueRow, { minHeight }]}>
           <View style={styles.value}>{children}</View>
         </View>
-        {warning != null ? (
-          <Text size="xs" color="warning" accessibilityRole="alert" aria-live="polite">
-            {warning}
-          </Text>
-        ) : null}
-        {error != null ? (
-          <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite">
-            {error}
-          </Text>
-        ) : null}
+        {annotations}
       </View>
     );
   }